COMPUTER EQUIPMENT AND SOFTWARE PURCHASED FROM A 
RADIO SHACK COMPANY-OWNED COMPUTER CENTER, RETAIL 
STORE OR FROM A RADIO SHACK FRANCHISEE OR DEALER AT ITS 
AUTHORIZED LOCATION 


LIMITED WARRANTY 


CUSTOMER OBLIGATIONS 


A. 


CUSTOMER. assumes full responsibility that this Radio Shack computer hardware purchased (the 
‘‘Equipment’’), and any copies of Radio Shack software included with the Equipment or licensed 
separately (the ‘‘Software’’) meets the specifications, capacity, capabilities, versatility, and other 
requirements of CUSTOMER. 

CUSTOMER assumes full responsibility for the condition and effectiveness of the operating 
environment in which the Equipment and Software are to function, and for its installation. 


RADIO SHACK LIMITED WARRANTIES AND CONDITIONS OF SALE 


A. 


For a period of ninety (90) calendar days from the date of the Radio Shack sales document 
received upon purchase of the Equipment, RADIO SHACK warrants to the original CUSTOMER that 
the Equipment and the medium upon which the Software is stored is free from manufacturing 
defects. THIS WARRANTY IS ONLY APPLICABLE TO PURCHASES OF RADIO SHACK EQUIPMENT 
BY THE ORIGINAL CUSTOMER FROM RADIO SHACK COMPANY-OWNED COMPUTER CENTERS, 
RETAIL STORES AND FROM RADIO SHACK FRANCHISEES AND DEALERS AT ITS AUTHORIZED 
LOCATION. The warranty is void if the Equipment’s case or cabinet has been opened, or if the 
Equipment or Software has been subjected to improper or abnormal use. If a manufacturing defect 
is discovered during the stated warranty period, the defective Equipment must be returned to a 
Radio Shack Computer Center, a Radio Shack retail store, participating Radio Shack franchisee or 
Radio Shack dealer for repair, along with a copy of the sales document or lease agreement. The 
original CUSTOMER'S sole and exclusive remedy in the event of a defect is limited to the 
correction of the defect by repair, replacement, or refund of the purchase price, at RADIO 
SHACK’S election and sole expense. RADIO SHACK has no obligation to replace or repair 
expendable items. 

RADIO SHACK makes no warranty as to the design, capability, capacity, or suitability for use of 
the Software, except as provided in this paragraph. Software is licensed on an “AS IS’’ basis, 
without warranty. The original CUSTOMER’S exclusive remedy, in the event of a Software 
manufacturing defect, is its repair or replacement within thirty (30) calendar days of the date of the 
Radio Shack sales document received upon license of the Software. The defective Software shall 
be returned to a Radio Shack Computer Center, a Radio Shack retail store, participating Radio 
Shack franchisee or Radio Shack dealer along with the sales document. 

Except as provided herein no employee, agent, franchisee, dealer or other person is authorized to 
give any warranties of any nature on behalf of RADIO SHACK. 

Except as provided herein, RADIO SHACK MAKES NO WARRANTIES, INCLUDING WARRANTIES 
OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 

Some states do not allow limitations on how long an implied warranty lasts, so the above 
limitation(s) may not apply to CUSTOMER. 


LIMITATION OF LIABILITY 


A. 


EXCEPT AS PROVIDED HEREIN, RADIO SHACK SHALL HAVE NO LIABILITY OR RESPONSIBILITY 
TO CUSTOMER OR ANY OTHER PERSON OR ENTITY WITH RESPECT TO ANY LIABILITY, LOSS 
OR DAMAGE CAUSED OR ALLEGED TO BE CAUSED DIRECTLY OR INDIRECTLY BY 
“EQUIPMENT” OR “SOFTWARE” SOLD, LEASED, LICENSED OR FURNISHED BY RADIO SHACK, 
INCLUDING, BUT NOT LIMITED TO, ANY INTERRUPTION OF SERVICE, LOSS OF BUSINESS OR 
ANTICIPATORY PROFITS OR CONSEQUENTIAL DAMAGES RESULTING FROM THE USE OR 
OPERATION OF THE ‘EQUIPMENT’ OR ‘‘SOFTWARE”’. IN NO EVENT SHALL RADIO SHACK BE 
LIABLE FOR LOSS OF PROFITS, OR ANY INDIRECT, SPECIAL, OR CONSEQUENTIAL DAMAGES 
ARISING OUT OF ANY BREACH OF THIS WARRANTY OR IN ANY MANNER ARISING OUT OF OR 
CONNECTED WITH THE SALE, LEASE, LICENSE, USE OR ANTICIPATED USE OF THE “EQUIPMENT” 


OR “SOFTWARE”. ; 
continued 
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NOTWITHSTANDING THE ABOVE LIMITATIONS AND WARRANTIES, RADIO SHACK’S LIABILITY 
HEREUNDER FOR DAMAGES INCURRED BY CUSTOMER OR OTHERS SHALL NOT EXCEED THE 
AMOUNT PAID BY CUSTOMER FOR THE PARTICULAR ‘EQUIPMENT’ OR ‘‘SOFTWARE’’ 
INVOLVED. 

RADIO SHACK shall not be liable for any damages caused by delay in delivering or furnishing 
Equipment and/or Software. 

No action arising out of any claimed breach of this Warranty or transactions under this Warranty 
may be brought more than two (2) years after the cause of action has accrued or more than four 
(4) years after the date of the Radio Shack sales document for the Equipment or Software, 
whichever first occurs. 

Some states do not allow the limitation or exclusion of incidental or consequential damages, so the 
above limitation(s) or exclusion(s) may not apply to CUSTOMER. 


RADIO SHACK SOFTWARE LICENSE 


RADIO SHACK grants to CUSTOMER a non-exclusive, paid-up license to use the RADIO SHACK Software 
on one computer, subject to the following provisions: 


G. 


Except as otherwise provided in this Software License, applicable copyright laws shall apply to the 
Software. 

Title to the medium on which the Software is recorded (cassette and/or diskette) or stored (ROM) 
is transferred to CUSTOMER, but not title to the Software. 

CUSTOMER may use Software on one host computer and access that Software through one or 
more terminals if the Software permits this function. 

CUSTOMER shall not use, make, manufacture, or reproduce copies of Software except for use on 
one computer and as is specifically provided in this Software License. Customer is expressly 
prohibited from disassembling the Software. 


CUSTOMER is permitted to make additional copies of the Software only for backup or archival 


purposes or if additional copies are required in the operation of one computer with the Software, 
but only to the extent the Software allows a backup copy to be made. However, for TRSDOS 
Software, CUSTOMER is permitted to make a limited number of additional copies for 
CUSTOMER’S own use. 

CUSTOMER may resell or distribute unmodified copies of the Software provided CUSTOMER has 
purchased one copy of the Software for each one sold or distributed. The provisions of this 
Software License shall also be applicable to third parties receiving copies of the Software from 
CUSTOMER. 

All copyright notices shall be retained on all copies of the Software. 


APPLICABILITY OF WARRANTY 


A. 


The terms and conditions of this Warranty are applicable as between RADIO SHACK and 
CUSTOMER to either a sale of the Equipment and/or Software License to CUSTOMER or to a 
transaction whereby RADIO SHACK sells or conveys such Equipment to a third party for lease to 
CUSTOMER. 

The limitations of liability and Warranty provisions herein shall inure to the benefit of RADIO 
SHACK, the author, owner and/or licensor of the Software and any manufacturer of the Equipment 
sold by RADIO SHACK. 


STATE LAW RIGHTS 


The warranties granted herein give the original CUSTOMER specific legal rights, and the original 
CUSTOMER may have other rights which vary from state to state. 
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Copyright 1983 Microware Systems Corporation, All Rights Reserved. 
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from Microware Systems Corporation. 
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any damages, including indirect or consequential, from use of the 
OS-9 operating system or reliance on the accuracy of this 
documentation. The information contained herein is subject to 
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INTRODUCTION 


The "C" programming language is rapidly growing in popularity 
and seems destined to become one of the most popular programming 
languages used for microcomputers. The rapid rise in the use of C 
is not surprising. C is an incredibly versatile and efficient 
language that can handle tasks that previously would have required 
complex assembly language programming. 


C was originally developed at Bell Telephone Laboratories as an 
implementation language for the UNIX operating system by Brian 
Kernighan and Dennis Ritchie. They also wrote a book titled "The C 
Programming Language" which is universally accepted as the standard 
for the language. It is an interesting reflection on the language 
that although no formal industry-wide "standard" was ever developed 
for C, programs written in C tend to be far more portable between 
radically different computer system as compared to so-called 
"standardized" languages such as BASIC, COBOL, and PASCAL. The 
reason C is so portable is that the language is so inherently 
expandable that if some special function is required, the user can 
create a portable extension to the language, as opposed to the 
common practice of adding additional statements to the language. 
For example, the number of ‘special-purpose BASIC dialects defies all 
reason. A lesser factor is the underlying UNIX operating systen, 
which is also sufficiently versatile to discourage 
nonstandardization of the language. Indeed, standard C compilers 
and Unix are intimately related. 


Fortunately, the 6809 microprocessor, the OS-9 operating 
system, and the C language form an outstanding combination. The 
6809 was specifically designed to efficiently run high-level 
languages, and its stack-oriented instruction set and versatile 
repertoire of addressing modes handle the C language very well. As 
mentioned previously, UNIX andcC are closely related, and because 
OS-9 is derived from UNIX, it also supports C to the degree that 
almost any application written in C can be transported from a UNIX 
system to an OS-9 system, recompiled, and correctly executed. 
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THE LANGUAGE IMPLEMENTATION 


OS-9 C is implemented almost exactly as described in ‘The C 
Programming Language' by Kernighan and Ritchie (hereafter referred 
to as K & R). A copy of this book, which serves as the language 
reference manual, is included with each software package. 


Although this version of C follows the-specification faith- 
fully, there are some differences. The differences mostly reflect 
parts of C that are obsolete or the constraints imposed by memory 
size limitations. 


DIFFERENCES FROM THE K & R SPECIFICATION 


- Bit fields are not supported. 


- Constant expressions for initializers may include arithmetic 
operators only if all the operands are of -type INT or CHAR. 


- The older forms of assignment operators, ‘'=+' or 's#', which 
are recognized by some C compilers, are not supported. You 
must use the newer forms '+=','#=' etc. 


- "ifdef (or #ifndef) ...[#else...] #endif" is supported but 
"#if <constant expression>" is not. 


- It is not possible to extend macro definitions or strings 
over more than one line of source code. 


- The escape sequence for new-line '\n' refers to the ASCII 
carriage return character (used by OS-9 for end-of-line), not 
linefeed.(hex 0A). Programs which use '\n' for end-of-line 
(which includes all programs in K & R), will still work 

. properly. 
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ENHANCEMENTS AND EXTENSIONS 


The "Direct" Storage Class 


The 6809 microprocessor instructions for accessing memory via 
an index register or the stack pointer can be relatively short and 
fast when they are used in C programs to access "auto" (function 
local) variables or function arguments. The instructions for 
accessing global variables are normally not so nice and must be four 
bytes long and correspondingly slow. However, the 6809 has a nice 
feature which helps considerably. Memory, anywhere in a single page 
(256 byte block), may be accessed with fast, two byte instructions. 
This is called the "direct page", and at any time its location is 
specified by the contents of the "direct page register" within the 
processor. The linkage editor sorts out where this should be, and 
it need not concern the programmer, who only needs to specify for 
the compiler which variables should be in the direct page to give 
the maximum benefit in code size and execution speed. 


To this end, a new storage class specifier is recognized by the 
compiler. In the manner of K & R page 192, the sc-specifier list 
is extended as follows: 

Se-specifier: auto 

static 

extern 

register 

typedef 

direct (extension) 
extern direct (extension) 
static direct (extension) 


The new key word may be used in place of one of the other sc- 
specifiers, and its effect is that the variable will be placed in 
the direct page. "DIRECT" creates a global direct page variable. 
"EXTERN DIRECT" references an EXTERNAL-type direct page variable; 
and "STATIC DIRECT" creates a local direct page variable. These new 
classes may not be used to declare function arguments. "Direct" 
variables can be initialized but will, as with other variables not 
explicitly initialized, have the value zero at the start of program 
execution. 255 bytes are available in the direct page (the linker 
requires one byte). Jf all the direct variables occupy less than the 
full 255 bytes, the remaining global variables will occupy the 
balance and memory above if necessary. If too many bytes of storage 
are requested in the direct page, the linkage editor will report an 
error, and the programmer will have to reduce the use of DIRECT-type 
variables to fit the 256 bytes addressable by the 6809. 


It should be kept in mind that "direct" is unique to this 


compiler, and it may not be possible to transport programs written 
using "direct" to other environments without modification. 
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Imbedded Assembly Language 


As versatile as C is, occasionally there are some things that 
can only be done (or done at maximum speed) in assembly language. 
The OS-9 C compiler permits user-supplied assembly-language 
statements to be directly embedded in C source programs. 


A line beginning with "#asm" switches the compiler into a mode 
which passes all subsequent lines directly to the assembly-language 
output, until a line beginning with "#endasm" is encountered. 
"fendasm" switches the mode back to normal. Care should be 
exercised when using this directive so that the correct code section 
is adhered to. Normal code from the compiler is in the PSECT (code) 
section. If your assembly code uses the VSECT (variable) section, 
be sure to put a ENDSECT directive at the end to leave the state 
correct for following compiler generated code. 


Control Character Escape Sequences 


The escape sequences for non-printing characters in character 
constants and strings (see K & R page 181) are extended as follows: 


linefeed (LF): \l (lower case ‘'ell') 
This is to distinguish LF (hex 0A) from \n which on OS-9 is the same 
as \r (hex OD). 


bit patterns: \NNN (octal constant) 
\d NNN (decimal constant) 
\xNN (hexadecimal constant) 
For example, the following all have a value of 255 (decimal): 


\37T \xff \d255 
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IMPLEMENTATION DEPENDENT CHARACTERISTICS 
K & R frequently refer to characteristics of the C language 
whose exact operations depend on the architecture and instruction 


set of the computer actually used. This section contains specific 
information regarding this version of C for the 6809 processor. 


Data Representation and Storage Requirements 


Each variable type requires a specific amount of memory for 
storage. The sizes of the basic types in bytes are as follows: 


Data Type size Internal Representation 

CHAR 1 two's complement binary 

INT 2 two's complement binary 

UNSIGNED 2 unsigned binary 

LONG 4 two's complement binary 

FLOAT 4 binary floating point (see below) 
DOUBLE 8 binary floating point (see below) 


This compiler follows the PDP-11 implementation and format in 
that CHARS are converted to INTs by sign extension, "SHORT" or 
"SHORT INT" means INT, "LONG INT" means LONG, and "LONG FLOAT" means 
DOUBLE. The format for DOUBLE values is as follows: 


(low byte) (high byte) 

$e fee meee meme ee mew ewe ee ee ewe mew ewww een femme er wene + 
! ! seven byte ! 1 byte ! 
!! mantissa | exponent | 

fo pew m ew www www wwe ww ww we www ewww www eww eee eww fo eeeeenene + 
* sign bit 


The form of the mantissa is sign and magnitude with an implied 
"7" bit at the sign bit position. The exponent is biased by 128. 
The format of a FLOAT is identical, except that the mantissa is only 
three bytes long. Conversion from DOUBLE to FLOAT is carried out by 
truncating the least significant (right-most) four bytes of the 
mantissa. The reverse conversion is done by padding the least 
significant four mantissa bytes with zeros. 


Register Variables 


One register variable may be declared in each function. The 
only types permitted for register variables are int, unsigned and 
pointer. Invalid register variable declarations are ignored; i.e. 
the storage class is made auto. For further detaiis see K & R page 
81. 
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A considerable saving in code size and speed can be made by 
judicious use of a register variable. The most efficient use is 
made of it for a pointer or a counter for a loop. However, if a 
register variable is used in a complex arithmetic expression, there 
is no saving. The "U" register is assigned to register variables. 


IMPORTANT NOTE: Upper and lower case letters cannot be mixed as in 
BasicO9. For example, Prog.c and prog.c are distinct names. Since 
the Color Computer is usually used in upper case only, it is 
necessary to enter the following commands to use upper AND lower 
case: TMODE -UPC and CLEAR<0>. 


Access To Command Line Parameters 


The standard C arguments "“arge" and "argv" are available to 
"main" as described in K & R page 110. The start-up routine for C 
programs ensures that the parameter string passed to it by the 
parent process is converted into null-terminated strings as expected 
by the progran. In addition, it will run together as a single 
argument any strings enclosed between single or double quotes ("'" 
or ft), If either is part of the string required, then the other 
should be used as a delimiter. 
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SYSTEM CALLS AND THE STANDARD LIBRARY 


Operating System Calls 


The system interface supports almost all the system calls of 
both OS-9 and UNIX. In order to facilitate the portability of 
programs from UNIX, some of the calls use UNIX names rather than 
OS-9 names for the same function. There are a few UNIX calls that 
do not have exactly equivalent OS-9 calls. In these cases, the 
library function simulates the function of the corresponding UNIX 
call. In cases where there are OS-9 calls that do not have UNIX 
equivalents, the OS-9 names are used. Details of the calls and a 
name cross-reference are provided in the "C System Calls" section of 
this manual. 


The Standard Library 


The C compiler includes a very complete library of standard 
functions. It is essential for any program which uses functions 
from the standard library to have the statement: 


"Zinclude <stdio.h>" 


See the "C Standard Library" section of this manual for details on 
the standard library functions provided. 


IMPORTANT NOTE: | If output via printf(), fprintf() or sprintf() of 
long integers is required, the program MUST call "pflinit()" at some 
point; this is necessary so that programs not involving LONGs do not 
have the extra LONGs output code appended. Similarly, if FLOATs or 
DOUBLES are to be printed, "pffinit()" MUST be called. These func- 
tions do nothing; existence of calls to them in a program informs 
the linker that the relevant routines are also needed. 
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RUN-TIME ARITHMETIC ERROR HANDLING 


K & R leave the treatment of various arithmetic errors open, 
merely saying that it is machine dependent. This implementation 
deals with a limited number of error conditions in a special way; it 
should be assumed that the results of other possible errors are 
undefined. 


Three new system error numbers are defined in <errno.h>: 


#define EFPOVR 40 /* floating point overflow or underflow #/ 

#define EDIVERR 41 /* division by zero #/ 

#define EINTERR 42 /* overflow on conversion of floating point 
to long integer #/ 


If one of these conditions occur, the program will send a 
Signal to itself with the value of one of these errors. If not 
caught or ignored, this will cause termination of the program with 
an error return to the parent process. However, the program can 
catch the interrupt using "signal()" or "intercept()" (see C System 
Calls), and in this case the service routine has the error number as 
its argument. 
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ACHIEVING MAXIMUM PROGRAM PERFORMANCE 


Programming Considerations 


Because the 6809 is an 8/16 bit microprocessor, the compiler 
can generate efficient code for 8 and 16 bit objects (CHARs, INTs, 
etc.). However, code for 32 and 64 bit values (LONGs, FLOATs, 
DOUBLES) can be at least four times longer and slower. Therefore 
don't use LONG, FLOAT, or DOUBLE where INT or UNSIGNED will do. 


The compiler can perform extensive evaluation of constant 
expressions provided they involve only constants of type CHAR, INT, 
and UNSIGNED. There is no constant expression evaluation at 
compile-time (except single constants and "casts" of them) where 
there are constants of type LONG, FLOAT, or DOUBLE, therefore, 
complex constant expressions involving these types are evaluated at 
run time by the compiled program. You should manually compute the 
value of constant expressions of these types if speed is essential. 


The Optimizer Pass 


The optimizer pass automatically occurs after the compilation 
passes. It reads the assembler source code text and removes 
redundant code and searches for code sequences that can be replaced 
by shorter and faster equivalents. The optimizer will shorten object 
code by about 11% with a significant increase in program execution 
speed. The optimizer is recommended for production versions of dee 
bugged programs. Because this pass takes additional time, the "-0" 
compiler option can be used to inhibit it during error-checking-only 
compilations. 


The Profiler 


The profiler is an optional method used to determine the 
frequency of execution of each function in a C program. It allows 
you to identify the most frequently used functions where algorithmic 
or C source code programming improvements will yield the greatest 
gains. 


When the "~P" compiler option is selected, code is generated at 
the beginning of each function to call the profiler module (called 
" prof"), which counts invocations of each function during program 
execution. When the program has terminated, the profiler 
automatically prints a list of all functions and the number of times 
each was called. The profiler slightly reduces program execution 
speed. See "prof.c" source for more information. 
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C COMPILER COMPONENT FILES AND FILE USAGE 


» 


Compilation of a C program by cc requires that the following 
files be present in the current execution directory (CMDS). 


OS-9 Level I Systems: 


ect compiler executive program 
c.prep macro pre-processor 
c.passi1 compiler pass 1 

ec.pass2 compiler pass 2 

c.opt assembly code optimizer 
c.asm relocating assembler 
e.link linkage editor 


OS-9 Level II Systems: 


ec2 compiler executive program 
c.prep macro pre-processor 

ec.comp compiler proper 

c.opt assembly code optimizer 
c.asm relocating assembler 
e.link linkage editor 


In addition a file called "clib.1" contains the standard lib- 
rary, math functions, and system library. The file "cstart.r" is 
the setup code for compiled programs. Both of these files must be 
located in a directory named "LIB" on drive /D1. The DEFS directory 
must also be on /D1. 


If, when specifying "#include" files for the preprocessor to 
read in, the programmer uses angle brackets, "<" and ">", instead of 
parentheses, the file will be sought starting at the "DEFS" 
directory. 


Temporary Files 


A number of temporary files are created in the current data 
directory during compilation, and it is important to ensure that 
enough space is available on the disk drive. As a rough guide, at 
least three times the number of blocks in the largest source file 
(and its included files) should be free. 


The identifiers "etext","edata", and "end" are predefined in the 
linkage editor and may be used to establish the addresses of the end 
of executable text, initialized data, and uninitialized data 
respectively. 
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RUNNING THE COMPILER 


There are two commands which invoke distinct versions of the 
compiler. "cc1" is for OS-9 Level I which uses a two pass compiler, 
and, ce2 is for Level II which uses a single pass version. Both 
versions of the compiler work identically, the main difference is 
that cecil has been divided into two passes to fit the smaller memory 
size of OS-9 Level I systems. In the following text, "cc" refers to 
either "cc1" or "ec2" as appropriate for your system. The syntax of 
the command line which calls the compiler is: 


ec [ option-flags ] file {file} 


One file at a time can be compiled, or a number of files may be 
compiled together. The compiler manages the compilation through up 
to four stages: pre-processor, compilation to assembler’ code, 
assembly to relocatable module, and linking to binary executable 
code (in OS=-9 memory module format). 


The compiler accepts three types of source files, provided each 


name on the command line has the relevant postfix as shown below. 
Any of the above file types may be mixed on the command line. 


File Name Suffix Conventions 


suffix Usage 
2c C source file 
a assembly language source file 
r relocatable module 
none executable binary (OS-9 memory module) 


There are two modes of operation: multiple source file and 
Single source file. The compiler selects the mode by inspecting 
the command line. The usual mode is single source and is specified 
by having only one source file name on the command line. ofr 
course, more than one source file may be compiled together by using 
the "#include"®™ facility in the source code. In this mode, the 
compiler will use the name obtained by removing the postfix from the 
name supplied on the command line, and the output file (and the 
memory module produced) will have this name. For example: 


ee prg.c 


will leave an executable file called "prg" in the current execution 
directory. 


The multiple source mode is specified by having more than one 
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source file name on the command line. In this mode, the object code 
output file will have the name "output" in the current execution 
directory, unless a name is given using the "-f=" option (see 
below). Also, in multiple source mode, the relocatable modules 
generated as intermediate files will be left in the same directories 
as their corresponding source files with the postfixes changed to 
".r",. For example: 


cc prgi.c /d0/fred/prg2.c 
will leave an executable file called "output" in the current 
execution directory, one called "prgi.r" in the current data 
directory, and "prg2.r" in "/d0/fred", 

CC -E=3 PNAME.C -F=PROG 
compiles the file called "PNAME.C" into an executable object file 
named "PROG" and sets the module revision level to 3. 

CC PROG.C -DIDENTIFIER=VALUE 
compiles the program with a definition identifier being passed to 


the compiler. The definition being passed is used within the source 
to control compilation via IFDEF/IFNDEF functions. 
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COMPILER OPTION FLAGS 


The compiler recognizes several command-line option flags which 
modify the compilation process where needed. All flags are 
recognized before compilation commences so the flags may be placed 
anywhere on the command line. Flags may be ran together as in "- 
ro", except where a flag is followed by something else; see "-f=" 
and "-d" for examples. 


-A suppresses assembly, leaving the output as assembler code ina 
file whose name is postfixed ".a", 


-E=<number> Set the edition number constant byte to the number 
given. This is an OS-9 convention for memory modules. 


-0 inhibits the assembly code optimizer pass. The optimizer will 
shorten object code by about 11% with a comparable increase in speed 
and is recommended for production versions of de-bugged programs. 


-P invokes’ the profiler to generate function invocation frequency 
statistics after program execution. 

-R suppresses linking library modules into an executable progran. 
Outputs are left in files with postfixes ".r", 


-M=<memory size> will instruct the linker to allocate <memory size> 
for data, stack, and parameter area. Memory size may be expressed 
in pages (an integer) or in kilobytes by appending "k" to an 
integer. For more details of the use of this option, see the 
"Memory Management" section of this manual. 


-L=<filename> specifies a library to be searched by the linker 
before the Standard Library and system interface. 


-F=<path> overrides the above output file naming. The output file 
will be left with <filename> as its name. This flag does not make 
sense in multiple source mode, and either the -a or -r flag is also 
present. The module will be called the last name in <path>. 


-C will output the source code as comments with the assembler code. 


-S stops the generation of stack-checking code. -S should only be 
used with great care when the application is extremely time-critical 
and when the use of the stack by compiler generated code is fully 
understood. 


-D identifier> is equivalent to "#define <identifier>" written in 
the source file. -D is useful where different versions of a program 
are maintained in one source file and differentiated by means of the 
"#ifdef" or "#ifndef" pre-processor directives. If the <identifier> 
is used as a macro for expansion by the pre-processor, "1"(one) will 
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be the expanded "value" unless the form "-d<identifier>=<string>" is 
used in which case the expansion will be <string>. 


COMMAND LINE AND OPTION FLAG EXAMPLES 


command line action output file(s) 
cc prg.c compile to an executable prg 

program 
ec prg.c -a compile to assembly prg.a 


language source code 


ec prg.c -r compile to relocatable prg.r 
module 
ec prgi.c prg2.c prg3.c compile to executable prgi.r, prge2.r, 
program prg3.r, output 
cc prgi.c prg2.a prg3.r compile prgi.c, ~ prgi.r, prg2.r 


assemble prg2.a and 
combine all into an 
executable program 


cc prgi.c prg2.c -a compile to assembly prg1l.a, prg2.a 
language source code 

ec prgi.c prg2.c -f=prg compile to executable preg 
program 
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The Object Code Module 


The compiler produces position-independent, reentrant 6809 code 
in a standard OS-9 memory module format. The format of an execut- 
able program module is shown below. Detailed descriptions of each 
section of the module are given on following pages. 


Module Section 
Offset Size (bytes) 
$m we www we ww ww em ww oe en nm eee eee + 
$00 ! 
! Module Header ! 8 
! 
Clete tet tn ot eo ! 
$09 ! Execution Offset J a+ 2 
| ew ew ew ww we mew mw ww mw ee enw eee eee ! ! 
$0B ! Permanent Storage Size ! ! 2 
| eee eww we ewe ee wee wee ee eee ! ! 
$0D ! Module Name ! ! 
§ e e e e e eo e e e e e e e e e ! ! 
Vv V <-=<+ 
: Executable Code : 
: String Literals : 
tte tt te ! 
! Initializing Data Size ! 2 
| mm mmm wwe wm eww www mew wee eee eee ee ! 
Vv Vv 
: Initializing Data : 
Cette ttt tt | 
! Data-text Reference Count ! 2 
| ew we ewww www wm www wee meee ewww ween = ! 
Vv Vv 
: Data-text Reference Offsets : 
| ew www ewww www wwe wwe wee ee eee eee ! 
{ Data-data Reference Count ! 2 
| we mmm wwe ew mew ww ee wee eee ene ee ! 
Vv Vv 
: Data-data Reference Offsets : 
| wm ww www wm mm ew ewe em www eww een ee ! 
! CRC Check Value ! 3 
errr + 
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Module Header 


This is a standard module header with the type/language byte set to 
$11 (Program + 6809 Object Code), and the attribute/revision byte 
set to $81 (Reentrant + 1). 


Execution Offset 


Used by OS-9 to locate where to start execution of the progran. 


Storage Size 


Storage size is the initial default allocation of memory for data, 
stack, and parameter’ area. For a full description of memory 
allocation, see the section entitled "Memory Management" located 
elsewhere in this manual. 


Module Name 


Module name is used by OS<9 to enter the module in the module 
directory. The module name is followed by the edition byte encoded 
in estart. If this situation is not desired it may be overridden by 
the -E= option in ec. 


Information 


Any strings preceded by the directive "info" in an assembly code 
file will be placed here. A major use of this facility is to place 
in the module the version number and/or a copyright notice. Note 
that the '‘#asm' pre-compiler instruction may be used in a C source 
file to enable the inclusion of this directive in the compiler- 
generated assembly code file. 


Executable Code 


The machine code instructions of the progran. 


String Literals 


Quoted strings in the C source are placed here. They are in the 
null-terminated form expected by the functions in the Standard 
Library. NOTE: the definition of the C language assumes that 
strings are in the DATA area and are therefore subject to alteration 
without making the program non-reentrant. However, in order to avoid 
the duplication of memory requirements which would be necessary if 
they were to be in the data area, they are placed in the TEXT 
(executable) section of the module. Putting the strings in the 
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executable section implies that no attempt should be made by a C 
programmer to alter string literals. They should be copied out 
first. The exception that proves the rule is the initialization of 
an array of type char like this: 


char message[] = "Hello world\n"; 


The string will be found in the array 'message' in the data area and 
can be altered. 


Initializing Data and its Size 


If a C program contains initializers, the data for the initial 
values of the variables is placed in this section. The definition 
of C states that all uninitialized global and static variables have 
the value zero when the program starts running, so the startup 
routine of each C program first copies the data from the module into 
the data area and then clears the rest of the data memory to nulls. 


Data References 


No absolute addresses are known at compile time under OS-9, so where 
there are pointer values in the initializing data, they must be 
adjusted at run time so that they reflect the absolute values at 
that time. The startup routine uses the two data reference tables 
to locate the values that need alteration and adjusts them by the 
absolute values of the bases of the executable code and data re- 
spectively. 


For example, suppose there are the following statements in the 
program being compiled: 


char ®p = "I'm a string!"; 
char #%q = &p; 


These declarations tell the compiler that there is to be a char 
pointer variable, ‘'p', whose initial value is the address of the 
string anda pointer to a char pointer, 'q', whose initial value is 
the address of ‘pt. The variables must be in the DATA section of 
memory at run time because they are potentially alterable, but 
absolute addresses are not known until run time, so the values that 
'"p' and ‘q*' must’ have are not known at compile time. The string 
will be placed by the compiler in the TEXT section and will not be 
copied out to DATA memory by the startup routine. The initializing 
data section of the program module will contain entries for 'p' and 
'q'. They will have as values the offsets of the string from the 
base of the TEXT section and the offset of the location of 'p' from 
the base of the DATA section respectively. 


The startup routine will first copy all the entries in the initial- 
izing data section into their allotted places in the DATA section. 
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Then it will scan the data-text reference table for the offsets of 
values that need to have the addresses of the base of the TEXR 
section added to. then. Among these will be "p" which, after 
updating, will point to the string which is in the TEXT section. 
Similarly, after a scan of the data-data references, "q" will point 
to(contain the absolute of) "p", 


MEMORY MANAGEMENT 


The C compiler and its support programs have default conditions 
such that the average programmer need not be concerned with details 
of memory management. However, there are situations where advanced 
programmers may wish to tailor the storage allocation of a program 
for special situations. The following information explains in 
detail how aC program's data area is allocated and used. 


Typical C Program Memory Map 


A storage area is allocated by OS-9 when the C program is executed. 
The layout of this memory is as follows: ” 


high addresses 


| <= SBRK() adds more 
| - | memory here 
| | 


$eeeween new ewe e ene + <= memend 


Current stack stack 


reservation -> 


{ 

| <= sp register 

rr | 

Vv ! 
! <= standard I/0 buffers 

free memory ! allocated here 
! 


Current top 


ow ep op CHD cop S88 CED 8D woe OOD 


of data -> cece cece cvcsveseee! <= IBRK() changes this 
! memory bound upward 
requested memory ! 
| meee ee nnn ee ! <-- end. 
! uninitialized ! 
! data ! 
| eee em nn nen ee eee ! <-- edata 
! initialized ! 
! data ! 
| ae ee ee ee ee == ! 
* ! direct page ! 
dpsiz ! variables ! 
Vv $e ww ewe mmm mmm wwe + <=-- y,dp registers 


low addresses 
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The overall size of this memory area is defined by the "storage 
size" value stored in the program's module header. This can be 
overridden to assign the program additional memory if the OS-9 Shell 
"#" command is used. 


The parameter area is where the parameter string from the 
calling process (typically the OS-9 Shell) is placed by the systen. 
The initializing routine for C programs converts the parameters into 
null-terminated strings and makes pointers to them available to 
'main()' via ‘arge' and ‘argv’. 


The stack area is the currently reserved memory for exclusive 
use of the stack. As each C function is entered, a routine in the 
system interface is called to reserve enough stack space for the use 
of the function with an addition of 64 bytes. The 64 bytes are for 
the use of user-written assembly code functions and/or the system 
interface and/or arithmetic routines. A record is kept of the 
lowest address so far granted for the stack. If the area requested 
would not bring this lower then the C function is allowed to 
proceed. If the new lower limit would mean that the stack area 
would overlap the data area, the program stops with the message: 


###8 STACK OVERFLOW ###* 
on the standard error output. Otherwise, the new lower limit is 
set, and the C function resumes as before. 


The direct page variables area is where variables reside 
that have been defined with the storage class ‘direct! in the C 
source code or in the ‘direct' segment in assembly code source. 
Notice that the size of this area is always at least one byte (to 
ensure that no pointer to a variable can have the value NULL or 0) 
and that it is not necessarily 256 bytes. 


The uninitialized data area is where the remainder of the 
uninitialized program variables’ reside. These two areas are, in 
fact, cleared to all zeros by the program entry routine. The 
initialized data area is where the initialized variables of the 
program reside. There are two globally defined values which may be 
referred to: ‘tedata' and 'end', which are the addresses of one byte 
higher than the initialized data and one byte higher than the 
uninitialized data respectively. Note that these are not variables; 
the values are accessed in C by using the '&' operator as in: 


high = é&end; 
low = &edata; 


and in assembler: 


leax end,y 
stx high,y 


The Y register points to the base of the data area and variables are 
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addresses using Y-offset indexed instructions. 


When the program starts running, the remaining memory is 
assigned to the "free" area. A program may call "ibrk()" to 
request additional working memory (initialized to zeros) from the 
free memory area. Alternatively, more memory can be dynamically 
obtained using the "sbrk()" which requests additional memory from 
the operating system and returns its lower bound. If this fails 
because OS-9 refuses to grant more memory for any reason "sbrk()*" 
will return -1. 


Compile Time Memory Allocation 


If not instructed otherwise, the linker will automatically 
allocate 1k bytes more than the total size of the program's 
variables and strings. This size will normally be adequate to cover 
the parameter area, stack requirements, and Standard Library file 
buffers. The allocation size may be altered when using the compiler 
by using the "=m" option on the command line. The memory 
requirements may be stated in pages, for example, 


cc prg.c =-m=2 
which allocates 512 bytes extra, or in kilobytes, for example: 
ec prg.c -m=10k. 


The linker will ignore the request if the size is less than 256 
bytes. 


The following rules can serve as a rough guide to estimate how 
much memory to specify: 


1. The parameter area should be large enough for any anticipated 
command line string. 


2. The stack should be not less than 128 bytes and should take 
into account the depth of function calling chains and any 
recursion. 


3. All function arguments and local variables occupy stack space 
and each function entered needs 4 bytes more for the return 
address and temporary storage of the calling function's register 
variable. 


4, Free memory is requested by the Standard Library I1/0 
functions for buffers at the rate of 256 bytes per accessed 
file. This does not apply to the lower level service request I/0 
functions such as "open()", "read()" or "write()" nor to 
"stderr" which is always un-buffered, but it does apply to both 
"stdin" and "stdout" (see the Standard Library documentation). 


Page 2-6 


MICROWARE C COMPILER USER'S GUIDE 
CHARACTERISTICS OF COMPILED PROGRAMS 


A good method for getting a feel for how much memory is 
needed by your program is to allow the linker to set the memory size 
to its usually conservative default value. Then, if the program runs 
with a variety of input satisfactorily but memory is limited on the 
system, try reducing the allocation at the next compilation. If a 
stack overflow occurs or an “ibrk()" call returns -1, then try 
increasing the memory next time. You cannot damage the system by 
getting it wrong, but data may be lost if the program runs out of 
space at a crucial time. It pays to be in error on the generous 
side. 
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INTRODUCTION TO C SYSTEM CALLS 


This section of the C compiler manual is a guide to the system 
calls available from C progranms. 


It is NOT intended as a definitive description of OS-9 service 
requests as these are described in the OS-9 SYSTEM PROGRAMMER'S 
MANUAL. However, for most calls, enough information is available 
here to enable the programmer to write system calls into programs 
without looking further. 


The names used for the system calls are chosen so that programs 
transported from other machines or operating systems should compile 
and run with as little modification as possible. However, care 
should be taken as the parameters and returned values of some calls 
may not be compatible with those on other systems. Programmers that 
are already familiar with OS-9 names and values’ should take 
particular care. Some calls do not share the same names as the 0S-9 
assembly language equivalents. The assembly language equivalent 
call is shown, where there is one, on the relevant page of the C 
call description, and a cross-reference list is provided for those 
already familiar with OS-9 calls. 


The normal error indication on return from a system call is a 
returned value of -1. The relevant error will be found in the pre- 
defined int "errno", Errno always contains the error from the last 
erroneous system call. Definitions for the errors for inclusion in 
the program are in "<errno.h>", 


In the "SEE ALSO" sections on the following pages, unless 
otherwise stated, the references are to other system calls. 


Where "#include" files are shown, it is not mandatory to 
include them, but it might be convenient to use the manifest 
constants defined in them rather than integers; it certainly makes 
for more readable programs. 
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Abort - stop the program and produce a core dump 
USAGE 
abort() 
DESCRIPTION 
This call causes a memory image to be written out to the file 


"core" in the current directory, and then the program exits 
with a status of 1. 
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Abs - Absolute value 
USAGE 


int abs(i) 
int i; 


DESCRIPTION 
ABS returns absolute value of its integer operand. 
CAVEATS 


You get what the hardware gives on the largest negative number. 


Page 3 = 3 


MICROWARE C COMPILER USER'S GUIDE 
C SYSTEM CALLS 


Access = give file accessibility 


USAGE 


access(fname, perm) 
char *name; 
int pern; 


DESCRIPTION 


Access returns 0 if the access modes specified in "perm" are 
correct for the user to access "fname". -1is returned if the 
file cannot be accessed. 


The value for "perm" may be any legal OS-9 mode as used for 
"open()" or "creat()", it may be zero, which tests whether the 
file exists, or the path to it may be searched. 


CAVEATS 


NOTE that the "perm" value is NOT compatible with other 
systems. 


DIAGNOSTICS 


The appropriate error indication, if a value of -1 is returned, 
may be found in "errno". 
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Chain - load and execute a new program 
USAGE 


chain(modname, paramsize, paramptr,type,lang,datasize) 
char *modname,*paramptr; 


ASSEMBLER EQUIVALENT 
os9 FS$CHAIN 
DESCRIPTION 


The action of F$CHAIN is described fully in the 0S-9 
documentation. Chain implements the service request as 
described with one important exception: chain will NEVER return 
to the caller. If there is an error, the process will abort 
and return to its parent process. It might be wise, therefore, 
for the program to check the existence and access permissions 
of the module before calling chain. Permissions may be checked 
by using "modlink()" or "modload()" followed by an "munlink()*". 


"Modname" should point to the name of the desired module. 
"Paramsize" is the length of the parameter string (which should 
normally be terminated with a "\n"), and "paramptr" points to 
the parameter. string. "Type" is the module type as found in 
the module header (normally 1: program), and "lang" should 
match the language nibble in the module header (C programs 
have 1 for 6809 machine code here). "Datasize" may be zero, or 
it may contain the number of 256 byte pages to give to the new 
process as initial allocation of data memory. 
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Chdir,Chxdir - change directory 


chdir (dirname) 
char dirname; 


ehxdir (dirname) 
char dirname; 


ASSEMBLER EQUIVALENT 


os9 I$CHGDIR 


DESCRIPTION 


These calls change the current data directory and the current 
execution directory, respectively, for the running task. 
"Dirname*® is a pointer to a string that gives a pathname for a 
directory. 


DIAGNOSTICS 


Each call returns 0 after a successful call, or -1 if "dirname" 
is not a directory path name, or it is not searchable. 


SEE ALSO 


OS-9 shell commands "chd" and Mohx", 
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Chmod - change access permissions of a file 
USAGE 
#include <modes.h> 


chmod( fname, perm) 
char *fname; 


DESCRIPTION 
Chmod changes the permission bits associated with a file. 
"Fname" must be ae pointer to a file name, and "perm" should 


contain the desired bit pattern. 


The allowable bit patterns are defined in the include file as 


follows: 
/* permissions #/ 

#define S_IREAD 0x01 /* owner read #/ 
#define S_IWRITE 0x02 /* owner write #/ 
#define S_EXEC 0x04 /* owner execute */ 
#define S_IOREAD 0x08 /* public read #/ 
#define S_IOWRITE 0x10 /* public write #/ 
#define S_IOEXEC 0x20 /* public execute #/ 
#define S_ISHARE 0x40 /* sharable #/ 
#define S_IFDIR 0x80 /* directory */ 

Only the owner or the super user may change the permissions of 

a file. 

DIAGNOSTICS 


A successful call returns NULL(O). A -1 is returned if the 
caller is not entitled to change permissions or "fname" cannot 
be found. 

SEE ALSO 


OS-9 command "attr" 
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Chown - change the ownership of a file 
USAGE 


chown( fname, ownerid) 
char *fname; 


DESCRIPTION 


This call is available only to the super user. "Fname" is a 
pointer to a file name, and "“ownerid" is the new user-id. 


DIAGNOSTICS 


Zero is returned from aé_e successful call. -1 is returned on 
error. 
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Close = close a file 
USAGE 
close(pn) 
ASSEMBLER EQUIVALENT 
0s9 I§$CLOSE 
DESCRIPTION 


Close takes a path number, "pn", as returned from system calls 
"open()", "creat()", or "dup()", and closes the associated 
file. 


Termination of a task always closes all open files 
automatically, but it is necessary to close files where 
multiple files are opened by the task, and it is desired to 
re-use path numbers to avoid going over the system or process 
path number limit. 


SEE ALSO 


creat(),open(),dup(). 
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Cre = compute a cyclic redundancy count 


USAGE 


ere(start,count,accum) 
char *start,accun[3]; 


ASSEMBLER EQUIVALENT 
os9 F§$CRC 
DESCRIPTION 


This call accumulates a ere into a three byte array at "accum" 
for "count" bytes starting at "start". All three bytes of 
"accum" should be initialized to Oxff before the first call to 
"ere()", However, repeated calls can be subsequently made to 
cover an entire module. If the result is to be used as an O0S-9 
module ere, it should have its bytes complemented before 
insertion at the end of the module. 
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Creat - create a new file 
USAGE 
#include <modes.h> 


creat( fname, perm) 
char *fname; 


ASSEMBLER EQUIVALENT 
os9 I$¢CREATE 
DESCRIPTION 


Creat returns a path number to a new file available for 
writing, giving it the permissions specified in "perm" and 
making the task user the owner. If, however, "fname" is the 
name of an existing file, the file is truncated to zero length, 
and the ownership and permissions remain unchanged. NOTE, 
that unlike the OS-9 assembler service request, creat does 
not return an error if the file already exists. "Access()" 
should be used to establish the existence of a file if it is 
important that a file*should not be overwritten. 


It is unnecessary to specify writing permissions in "perm" in 
order to write to the file in the current task. 


The permissions allowed are defined in the include file as 
follows: 
/* permissions */ 

#define S_IPRM Oxff /* mask for permission bits #/ 

#define S_IREAD 0x01 /* owner read #/ 

#define S_IWRITE 0x02 /* owner write #/ 

#define S_IEXEC 0x04 /* owner execute #*/ 

#define S_IOREAD 0x08 /* public read *#/ 

#define S_IOWRITE 0x10 /* public write #/ 

#define S_IOEXEC 0x20 /* public execute */ 

#define S_ISHARE 0x40 /* sharable #/ 


Directories may not be created with this call; use "mknod()" 
instead. ; 


DIAGNOSTICS 
This call returns -1 if there are too many files open. If the 
pathname cannot be searched, if permission to write is denied, 
or if the file exists and is a directory. 

SEE ALSO 


write(),close(),chmod() 
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Defdrive - get default system drive 
USAGE 
char *defdrive() 
DESCRIPTION 
A call to defdrive returns a pointer to a string containing the 
name of the default system drive. The method used is to 
consult the "Init" module for the default directory name. The 
name is copied to a static data area and a pointer to it is 
returned. 


DIAGNOSTICS 


-1 is returned if the "Init" module cannot be linked to. 
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Dup - duplicate an open path number 
USAGE 
dup(pn) 
ASSEMBLER EQUIVALENT 
os9 I$DUP 
DESCRIPTION 
Dup takes the path number, "pn", as returned from "open()" or 
"creat()" and returns another path number associated with the 
same file. 
DIAGNOSTICS 


A -1is returned if the call fails because there are too many 
files open or the path number is invalid. 


SEE ALSO 


open() ,creat() ,close() 
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Exit, Exit - task termination 
USAGE 
exit(status) 
_exit(status) 
ASSEMBLER EQUIVALENT 
os9 FS$EXIT 
DESCRIPTION 
Exit is the normal means of terminating a task. Exit does any 
cleaning up operations required before terminating, such as 
flushing out any file buffers (see Standard I/o), but _exit 


does not. 


A task finishing normally, that is returning from "main()", 
is equivalent to a call - "exit(0)". 


The status passed to exit is available to the parent task if it 
is executing a "wait". 


SEE ALSO 


wait() ° 
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Getpid - get the task id 
USAGE 
getpid() 
ASSEMBLER EQUIVALENT 
os9 F$ID 
DESCRIPTION 
A number unique to the current running task is often useful in 
creating names for temporary files. This call returns the 
task's system id (as returned to its parent by "os9fork"). 


SEE ALSO 


gsi 5 
os9fork() Standard Library function mktemp. 


Page 3 = 15 


MICROWARE C COMPILER USER'S GUIDE 


C SYSTEM CALLS 


Getstat - get file status 


USAGE 
#include <sgstat.h> 
getstat(code,filenun, buffer) /* code 0 #/ 
char *buffer; 
getstat(code,filenum) /* codes 1 and 6 #/ 
getstat (code, filenum,size) /* code 2 #/ 


long *size; 


getstat(code,filenun, pos) /* code 5 #/ 


long *pos; 
ASSEMBLER EQUIVALENT 
os9 I$GETSTT 


DESCRIPTION 


A full description of getstat can be found in the OS-9 System 
Programmer's Manual. 


"Code" must be the value of one of the standard codes for the 
getstat service request. "filenum" must be the path number of 


an open file. 


The form of the call depends on the value of "code", 


Code 0: 


Code 1: 


Code 2 


Code 5 


Code 6 


"Buffer" must be the address of a 32 byte 


buffer into which the relevant status packet 
is copied. The header file has the 
definitions of the various file and device 
structures for use by the progran. 


Code 1 only applies to SCF devices and to 
test for data available. The return value is 
zero if there is data available. -1 is 
returned if there is no data. 


"Size" should be the address of a long 
integer into which the current file size is 
placed. The return value of the function is 
-1 on error and 0 on success. 


"Pos" should be the address of a long integer 
into which the current file size is placed. 
The return value of the function is -1 on 
error and 0 on success. 

Returns -1 on EOF and error and 0 on success. 
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NOTE that when one of the previous calls returns -1, the 
actual error is returned in errno. 
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Getuid - return user id 

USAGE 

getuid() 
ASSEMBLER EQUIVALENT 

os9 F$ID 
DESCRIPTION 


Getuid returns the real user id of the current task (as 
maintained in the password file). 
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Intercept - set function for interrupt processing 
USAGE 


intercept(func) 
int (#func)(); /* i.e. "func" is a pointer to a function 
returning an int #/ 


ASSEMBLER EQUIVALENT 
F$ICPT 
DESCRIPTION 


Intercept instructs OS-9 to pass control to the function "func" 
when an interrupt(signal) is received by the current process. 


If the interrupt processing function has an argument, it will 
contain the value of the signal received. On return from 
"func", the process resumes at the point in the program where 
it was interrupted by the signal. "Interrupt()" is an 
alternative to the use of "signal()" to process interrupts. 


As an example, suppose we wish to ensure that a partially 
completed output file is deleted if an interrupt is received. 
The body of the program might include: 


char *temp_ file = "temp"; /# name of temporary file #/ 


int pn = 0; /* path number #/ 
int intrupt(); /* predeclaration #/ 
intercept(intrupt); /* route interrupt processing *#/ 


pn = creat(temp_file,3); /# make a new file #/ 
write(pn,string,count) /* write string to temp file #/ 


close(pn); 
pn=0; 
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The interrupt routine might be coded: 
intrupt(sig); 
{ 
if (pn){ /* only done if pn refers to an open file #/ 
close(pn);3 


unlink(temp_file); /# delete #/ 


} 
exit(sig); 
} 


CAVEATS 
"Intercept()" and "signal()" are mutually incompatible so that 
calls to both must not appear in the same program. The linker 
guards against this by giving an "entry name clash - _sigint" 
error if it is attempted. 

SEE ALSO 


signal() 
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Kill - send an interrupt to a task 


USAGE 


#include <signal.h> 
kill(tid,interrupt) 


DESCRIPTION 


Kill sends the interrupt type "interrupt" to the task with id 
"tid®, 


Both tasks, sender and receiver, must have the same user id 
unless the user is the super user. 


The include file contains definitions of the defined signals as 
follows: 


/* OS-9 signals #/ 


#define SIGKILL 0 /* system abort (cannot be caught or 
ignored) #/ 

#define SIGWAKE 1 /* wake up #/ 

#define SIGQUIT 2 /* keyboard abort #/ 

#define SIGINT 3 /* keyboard interrupt #/ 


Other user-defined signals may, of course, be sent. 


DIAGNOSTICS 


Kill returns 0 from a successful call and -1 if the task does 
not exist, the effective user ids do not match, or the user is 
not the system manager. 


SEE ALSO 


Signal() OS-9 shell command "kill" 
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Lseek —- position in file 


USAGE 


long lseek(pn, position, type) 
long position; 


ASSEMBLER EQUIVALENT 


os9 I$SEEK 


DESCRIPTION 


The read or write pointer for the open file with the path 
number, "pn", is positioned by lseek to the specified place in 
the file. The "type" indicates from where "position" is to be 
measured: if 0, from the beginning of the file, if 1, from the 
current location, or if 2, from the end of the file. 


Seeking to a location beyond the end of a file open for 
writing and then writing to it, creates a "hole" in the file. 
which appears to be filled with zeros from the previous end to 
the position sought. 


The returned value is the resulting position in the file unless 
there is an error, so to find out the current position use 


lseek(pn,01,1); 


CAVEATS 


The argument "position" MUST be a long integer. Constants 
Should be explicitly made long by appending an "1", as above, 
and other types should be converted using a cast; 


e.g. lseek(pn,(long)pos,1); 


Notice also, that the return value from lseek is itself a long 
integer. 


DIAGNOSTICS 


-1 is returned if "pn" is a bad path number, or attempting to 
seek to a position before the beginning of a file. 


SEE ALSO 


open(),creat() Standard Library function "fseek" 
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Mknod - create a directory 
USAGE 
#include <modes.h> 


mknod(fname,desc) 
char *fname; 


ASSEMBLER EQUIVALENT 
os9 I$¢MAKDIR 


DESCRIPTION 


This call may be used to create a new directory. "Fname" 
Should point to ae string containing the desired name of the 
directory. "Desc" is a descriptor specifying the desired mode 


(file type) and permissions of the new file. 


The include file defines the possible values for "desc" 


follows: 

#define S_IREAD 0x01 /* owner read */ 
#define S_IWRITE 0x02 /* owner write #/ 
#define S_IEXEC 0x04 /* owner execute #/ 
#define S_IOREAD 0x08 /* public read #/ 
#define S_IOWRITE 0x10 /* public write #/ 
#define S_IOEXEC 0x20 /* public execute #/ 
#define S_ISHARE 0x40 /# sharable #/ 

DIAGNOSTICS 


zero is returned if the directory has been successfully made; - 


1 if the file already exists. 
SEE ALSO 


OS-9 command "makdir" 
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Modload, Modlink - return a pointer to a module structure 
USAGE 

#include <module.h> 

mod_exec #modlink(modname, type, language) 

char *modname; 

mod_exec *modload( filename, type, language) 


char *filename; 


ASSEMBLER EQUIVALENT 


os9 FS$LINK 
os9 F$LOAD 
DESCRIPTION 


Each of these calls return a pointer to an OS-9 memory module. 


Modlink will search the module directory for a module with the 
same name as "modname" and, if found, increment its link count. 


Modload will open the file which has the path list specified by 
"filename" and loads modules from the file adding them to the 
module directory. The returned value is a pointer to the first 
module loaded. 
Above, each is’ shown as returning a pointer to an executable 
module, but it will return a pointer to whatever type of module 
is found. 

DIAGNOSTICS 
-1 is returned on error. 


SEE ALSO 


munlink( ) 
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Munlink - unlink a module 
USAGE 
#include <module.h> 
munlink(mod) 
mod_exec mod; 
ASSEMBLER EQUIVALENT 
os9 FS$UNLINK 


DESCRIPTION 


This call informs the system that the module pointed to by 


"“mod* is no longer required by the current process. Its 


count is decremented, and the module is removed from the module 


directory if the link count reaches zero. 
SEE ALSO 


modlink() ,modload() 
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_0s9 = system call interface from C programs 


USAGE 


#include <os9.h> 


_0s9( code, reg) 
char code; 
struct registers treg; 


DESCRIPTION 


_0s9 enables a programmer to access virtually any OS-9 system 
call directly from aC program without having to resort to 
assembly language routines. 


Code is one of the codes that are defined in 0s9.h. os9.h 
contains codes for the F$ and I$ function/service requests, and 
it also contains getstt, setstt, and error codes. 


The input registers(reg) for the system calls are accessed by 
the following structure that is defined in os9.h: 


struct registers { 
char rg_cc,rg_a,rg_b,rg dup; 
unsigned rg_x,rg_y,rg_u; 

}; . 


An example program that uses _os9 is presented on the following 
page. 


DIAGNOSTICS 


-1 is returned if the OS-9 call failed. 0O is returned on 
success. 
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Program example: 


#include <os9.h> 
#include <modes.h> 


/* this program does an I$GETSTT call to get file size #/ 
main(arge,argv) 
int arge; 
char **argv; 
{ 
struct registers reg; 
int path; 


/* tell linker we need longs *#/ 
pflinit(); 


/* low level open(file name is first command line param #/ 
path=open(#++argv,S_IREAD); 


/* set up regs for call to OS-9 #/ 
reg.rg_a=path; 
reg.rg_b=SS_SIZE? 


if(_os9(I_GETSTT,é&reg) == 0) 
printf("filesize = 41x\n", /#® success #/ 
(long) (reg.rg_x << 16)+reg.rg_u); 


else printf("0S9 error #%d\n",reg.rg_b & Oxff); /#failed#/ 


dumpregs(&reg); /# take a look at the registers #/ 


} 

dumpregs(r) 

register struct registers fr; 

{ 
printf("cec=Z02x\n",r->org ce & Oxff); 
printf("* a=Z02x\n",r->rg_a & Oxff); 
printf(" b=Z02x\n",r->org_b & Oxff); 
printf("dp=%02x\n",r->rg_ dp & Oxff); 
printf(" x=Z04x\n",r-org x); 
printf("™ y=Z04x\n",r-org_y); 
printf(" u=Z0O4x\n",r-org u); 

} 
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Open —- open a file for read/write access 


USAGE 


open( fname, mode) 
char *fname; 


ASSEMBLER EQUIVALENT 


os9 I$OPEN 


DESCRIPTION 


This call opens an existing file for reading if "mode" is 1, 
writing if "mode" is 2, or reading and writing if "mode" is 3. 
NOTE that these values are OS-9 specific and not compatible 
with other systems. "Fname" should point to ae string 
representing the pathname of the file. 


Open returns an integer as "path number" which should be used 
by i/o system calls referring to the file. 


The position where reads or writes start is at the beginning of 
the file. 


DIAGNOSTICS 


-1 is returned if the file does not exist, if the pathname 
cannot be searched, if too many files are already open, or if 
the file permissions deny the requested mode. 


SEE ALSO 


Creat(),read(),write(),dup(),close() 
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Os9fork - create a process 
USAGE 


os9fork(modname, paramsize, paramptr,type,lang,datasize) 
char *modname,*paramptr; 


ASSEMBLER EQUIVALENT 
os9 F$FORK 


DESCRIPTION 


The action of F$FORK is described fully in the O0S-9 System 
Programmer's Manual. Os9fork will create a process that will 
run concurrently with the calling process. When the forked 
process terminates, it will return to the calling process. 


"Modname"™" should point to the name of the desired module. 
"Paramsize" is the length of the parameter string which should 
normally be terminated with a '\n', and "paramptr" points to 
the parameter string. "Type" is the module type as found in 
the header(normally 1: program), and "lang" should match the 
language nibble in ‘the module header( C programs have 1 for 
6809 machine code here). "Datasize" may be zero, or it may 
contain the number of 256 byte pages to give to the new process 
as initial allocation of memory. 


DIAGNOSTICS 


-1 will be returned on error, or the ID number of the child 
process will be returned on success. 
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Pause - halt and wait for interrupt 
USAGE 
pause () 
ASSEMBLER EQUIVALENT 


os9 I$SLEEP with a value of 0 
DESCRIPTION 


Pause may be used to halt a task until an interrupt is received 
from "kill". 


Pause always returns -1. 
SEE ALSO 


kill(),signal() OS-9 shell command "kill" 
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Prerr - print error message 


USAGE 


prerr(filnun,errcode) 


ASSEMBLER EQUIVALENT 
os9 F$PERR 


DESCRIPTION 


PRERR prints an error message on the output path as specified 


by "filnum" which must be the path number of an open file. The 


message depends on "errcode" which will normally be a standard 


OS-9 error code. 
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Read,Readln - read from a file 
USAGE 


read(pn, buffer,count) 
char *buffer; 


readln(pn, buffer, count) 
char *buffer; 


ASSEMBLER EQUIVALENT 
os9 I$READ 
os9 I$READLN 
DESCRIPTION 


The path number, "pn", is an integer which is one of the 
standard path numbers 0, 1, or 2, or the path number should 
have been returned by a successful call to "open", "creat", or 
"dup", "Buffer" is a pointer to space with at least "count" 
bytes of memory into which read will put the data from the 
file. 


It is guaranteed that at most "count" bytes will be read, but 
often less will be, either because, for readln, the file 
represents a terminal and input stops at the end of a line, or 
for both, end-of-file has been reached. 


Readln causes "line-editing" such as echoing to take place and 
returns once the first "\n" is encountered in the input or the 
number of bytes requested has been read. Readln is the 
preferred call for reading from the user's terminal. 


Read does not cause any such editing. See the OS-9 manual for 
a fuller description of the actions of these calls. 


DIAGNOSTICS 


Read and readin return the number of bytes actually read (0 at 
end-of-file) or -1 for physical i/o errors, a bad path number, 
or a ridiculous "count". 


NOTE that end-of-file is not considered an error, and no error 
indication is returned. Zero is returned on EOF. 


SEE ALSO 
open(),creat(),dup() 
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Sbrk,Ibrk - request additional working memory 


char *sbrk( increase) 
char *ibrk( increase) 


DESCRIPTION 


Sbrk requests an allocation from free memory and returns a 
pointer to its base. 


"Sprk()" requests the system to allocate "new" memory from 
outside the initial allocation. 


Users should read the Memory Management section of this manual 
for a fuller explanation of the arrangement. 


Ibrk requests memory from inside the initial memory allocation. 


DIAGNOSTICS 


Sbrk and ibrk return -1 if the requested amount of contiguous 
memory is unavailable. 
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Setpr - set process priority 
USAGE 
setpr(pid,priority) 
ASSEMBLER EQUIVALENT 
os9 F$SPRIOR 
DESCRIPTION 
SETPR sets the process identified by "pid"(process id) to have 
a priority of "priority". The lowest priority is 0 and the 
highest is 255. 
DIAGNOSTICS 


The call will return -1 if the process does not have the same 
user id as the caller. 
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Setime,Getime - Set and get system time 
USAGE 


#include <time.h> 

setime(byffer) 

getime(buffer) 

struct sgtbuf *buffer /* defined in time.h */ 


ASSEMBLER EQUIVALENT 


os9 F$STIME 
os9 G$GTIME 


DESCRIPTION 


GETIME returns system time in buffer. 
SETIME sets system time from buffer. 
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Setuid - set user id 
USAGE 
setuid(uid) 
ASSEMBLER EQUIVALENT 
os9 F$SUSER 
DESCRIPTION 
This call may be used to set the user id for the current task. 


Setuid only works if the caller is the super user(user id 0). 


DIAGNOSTICS 


Zero is returned from a successful call, and -1 is returned on 
error. 


SEE ALSO 


getuid() 
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Setstat - set file status 
USAGE 


#include <sgstat.h> 
setstat(code,filenun, buffer) /* code 0 #/ 
char *buffer; 


setstat(code,filenum, size) /* code 2 #/ 
long size; 


ASSEMBLER EQUIVALENT 
os9 F$SETSTT 
DESCRIPTION 


For a detailed explanation of this call, see the OS-9 System 
Programmer's Manual. 


"Filenum" must be the path number of a currently open file. 
The only values for code at this time are 0 and 2. When "code® 
is 0, "buffer" should be the address of a 32 byte structure 
which is written to the option section of the path descriptor 
of the file. The header file contains definitions of various 
structures maintained by OS-9 for use by the programmer. When 
code is 2, "size" should be a long integer specifying the new 
file size. 
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Signal - catch or ignore interrupts 


#include <signal.h> 


(#signal(interrupt,address) )() 
(#address)(); 


(Which means:"signal" returns a pointer to a function, 
naddress" is a pointer to a function.) 


DESCRIPTION 


This call is a comprehensive method of catching or ignoring 
signals sent to the current process. Notice that "kill()" does 
the sending of signals, and "signal()" does the catching. 


Normally, a signal sent to a process causes it to terminate 
with the status of the signal. If, in advance of _ the 
anticipated signal, this system call is used, the program has 
the choice of ignoring the signal or designating a function to 
be executed when it is received. Different functions may be 
designated for different signals. 


The values for "address" have the following meanings: 


0 = reset to the default i.e. abort when received 

1 = ignore; this will apply until reset to another 
value 

Otherwise: taken to. be the address of aC function which 
is to be executed on receipt of the signal. 


If the latter case is chosen, when the signal is received by 
the process the "address" is reset to 0, the default, before 
the function is executed. This means that if the next signal 
received should be caught then another call to "signal()®" 
should be made immediately. This is normally the first action 
taken by the "interrupt" function. The function may access the 
signal number which caused its execution by looking at its 
argument. On completion of this function the program resumes 
at the point at which it was "interrupted" by the signal. 


An example should help to clarify all this. Suppose a program 
needs to create a temporary file which should be deleted before 
exiting. The body of the program might contain fragments like 
this; 


pn = creat("temp",3); /* ereate a temporary file #/ 
signal(2,intrupt); /# ensure tidying up #/ 
signal(3,intrupt); 

write(pn,string,count); /* write to temporary file #/ 
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close(pn); /* finished writing #/ 
unlink("temp") ; /* delete it #/ 
exit(0); /* normal exit #/ 


The call to "signal()" will ensure that if a keyboard or quit 
Signal is received then the function "“intrupt()" will be 
executed and this might be written: 


intrupt(sig) 

{ 

close(pn); /* close it if open #/ 

unlink("temp"); /* delete it #/ 

exit(sig); /* received signal as exit 
status#/ 

} 


In this case, as the function will be exiting before another 
signal is received, it is unnecessary to call "signal()" again 
to reset its pointer. Note that either the function 
"intrupt()" should appear in the source code before the call to 
"signal()", or it should be pre-declared. 


The signals used by OS-9 are defined in the header file. as 
follows: 


/* OS-9 signals #/ 


#define SIGKILL 0 /* system abort (cannot be caught or 
ignored) #/ 

#define SIGWAKE 1 /* wake up #/ 

#define SIGQUIT 2 /* keyboard abort #/ 

#define SIGINT 3 /* keyboard interrupt #/ 

/* special addresses #/ 

#define SIG_DFL 0 /* reset to default #/ 

#define SIG_IGN 1 /* ignore *#/ 


Please note that there is another method of trapping signals, 
namely "“intercept()" (q.v.). However, since "signal()" and 
"intercept()" are mutually incompatible, calls to both of them 
must not appear in the same progran. The link-loader will 
prevent the creation of an executable program in which both are 
called by aborting with an "entry name clash" error for 
"_sigint", 


SEE ALSO 


intercept() OS-9 shell command "kill" kill() 
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Stacksize, Freemem - obtain stack reservation size 


USAGE 


stacksize() 
freemem( ) 


DESCRIPTION 


For a description of the meaning and use of this call, the user 
is referred to the Memory Management section of this manual. 


If the stack check code is in effect, a call to 
return the maximum number of bytes of stack used 
the call. This call can be used to determine 
required by a progran. 


Freemem() will return the number of bytes of the 
not been used. 
SEE ALSO 


stacksize will 
at the time of 
the stack size 


stack that has 


ibrk(),sbrk(),freemem() Global variable "“memend" and value 


"end", 
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Strass - byte by byte copy 
USAGE 


_S8trass(s1,s2,count) 
char *s1,#s2; 


DESCRIPTION 


Until such time as the compiler can deal with structure 


assignment, this function is useful for copying one structure 
to another. 


"Count" bytes are copied from memory location at "s2" to memory 
at "si" regardless of the contents. 
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Tsleep - put process to sleep 
USAGE 
tsleep(ticks) 
ASSEMBLER EQUIVALENT 
os9 F$SLEEP 


DESCRIPTION 


Tsleep deactivates the calling process for a specified number 


of system "ticks" or indefinitely if "ticks" is zero. 
is system dependent but is usually 100ms. 


For a fuller description of this call, see the OS-9 System 


Programmer's Manual. 
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Unlink - remove directory entry 


unlink( fname) 


ASSEMBLER EQUIVALENT 


os9 I$DELETE 


DESCRIPTION 


Unlink deletes the directory entry whose name is pointed to by 
"fname", If the entry was the last link to the file, the file 
itself is deleted and the dise space occupied made available 
for re-use. If, however, the file is open, in any active task, 
the deletion of the actual file is delayed until the file is 
closed. 


ERRORS 


zero is returned from a successful call, -1 if the file does 
not exist, if its directory is write-protected, or cannot be 
searched, if the file is a non-empty directory or a device. 


SEE ALSO 


OS-9 command "kill" link() 


Page 3 = 43 


MICROWARE C COMPILER USER'S GUIDE 
C SYSTEM CALLS 


Wait ~ wait for task termination 


USAGE 


wait(status) int *status; 


wait(0) 


ASSEMBLER EQUIVALENT 


os9 FSWAIT 


DESCRIPTION 


Wait is used to halt the current task until a child task has 
terminated. 


The call returns the task id of the terminating task and places 
the status of that task in the integer pointed to by "status" 
unless "status" is 0. A wait must be executed for each child 
task spawned. 


The status will contain the argument of the "exit" or "_exit" 
call in the child task or the signal number if it was 
interrupted. A normally terminating C program with no call to 
"exit" or "_exit" has an implied call of "exit(0)®. 


CAVEATS 


NOTE that the status is the OS-9 status code and is not 
compatible with codes on other systems. 


DIAGNOSTICS 


-1 is returned if there is no child to be waited for. 


SEE ALSO 


fork(),signal(),exit(),_exit() 
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Write,Writeln - write to a file or device 


USAGE 


write(pn,buffer,count) char *buffer; 


writeln(pn,buffer,count) char *buffer; 


ASSEMBLER EQUIVALENT 


os9 I$WRITE 


os9 I$WRITLN 


DESCRIPTION 


"Pn®™ must be a value returned by "open", "creat" or "dup" or 
should be a O(stdin), 1(stdout), or 2(stderr). 


"Buffer" should point to an area of memory from which "count" 
bytes are to be written. Write returns the actual number of 
bytes written, and if this is different from "count", an 
error has occurred. 


Writes in multiples of 256 bytes to file offset boundaries of 
256 bytes are the most efficient. 


Write causes no "line-editing" to occur on _ output. Writeln 
causes line-editing and only writes up to the first "\n" in the 
buffer if this is found before "count" is exhausted. For a 
full description of the actions of these calls the, reader is 
referred to the OS-9 documentation. 


DIAGNOSTICS 


-1 is returned if "pn" is a bad path number, if "count" is 
ridiculous or on physical i/o error. 


SEE ALSO 


creat() ,open() 
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INTRODUCTION TO THE C STANDARD LIBRARY 


The Standard Library contains functions which fall into two 
classes: high level I/0 and convenience. 


The high level I/0 functions provide facilities that are 
normally considered part of the definition of other languages; for 
example, the FORMAT "statement" of Fortran. In addition, automatic 
buffering of I/O channels improves the speed of file access because 
fewer system calls are necessary. 


The high level I/0 functions should not be confused with the 
low level system calls with similar names. Nor should "file 
pointers" be confused with "path numbers", The standard library 
functions maintain a structure for each file open that holds status 
information and a pointer into the files buffer. A user program 
uses a pointer to this structure as the "identity" of the file 
(which is provided by "fopen()"), and passes it to the various 
I/O functions. The I/O functions will make the low level system 
calls when necessary. 


USING A FILE POINTER IN A SYSTEM CALL, OR A PATH NUMBER IN A 
STANDARD LIBRARY CALL, is a common mistake among beginners to C and, 
if made, will be sure to CRASH YOUR PROGRAM. 


The convenience functions include facilities for copying, 
comparing, and concatenating strings, converting numbers to strings, 
and doing the extra work in accessing system information such as the 
time. 


In the pages which follow, the functions available are 
described in terms of what they do and the parameters they expect. 
The "USAGE*" section shows the name of the function and the type 
returned (if not int). The declaration of arguments are shown as 
they would be written in the function definition to indicate the 
types expected by the function. If it is necessary to include a 
file before the function can be used, it is shown in the "USAGE" 
section by "#include <filename>". 


Most of the header files that are required to be included, must 
reside in the "DEFS" directory on the default system drive. If the 
file is included in the source program using angle bracket 
delimiters instead of the usual double quotes, the compiler will 
append this path name to the file name. For example, "#include 
<stdio.h>" is equivalent to "#include /d0/defs/stdio.h", if "/d0" is 
the path name of the default system drive. 


PLEASE NOTE that if the type of the value returned by a 
function is not INT, you should make a predeclaration in your 
program before calling it. For example, if you wish to use 
"atof()", you should predeclare by having "double atof();" somewhere 
in your program before a call to it. Some functions which have 
associated header files in the DEFS directory that should be 
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included, will be pre-declared for you in the header. An example of 
this is "ftell()" which is predeclared in "stdio.h". If you are in 
any doubt, read the header file. 
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Atof,Atoi,Atol - ASCII to number conversions 
USAGE 


double atof(ptr) 
char *ptr; 


long atol(ptr) 
char *ptr; 


int atoi(ptr) 
char *ptr; 


DESCRIPTION 


Conversions of the string pointed to by "ptr" to the relevant 
number type are carried out by these functions. They cease to 
convert a number when the first unrecognized character is 
encountered. 


Each skips leading spaces and tab characters. Atof() 
recognizes an optional sign followed by a digit string that 
could possibly contain a decimal point, then an optional "ef" 
or "E", an optional sign and a digit string. Atol() and atoi() 
recognize an optional sign and a digit string. 


CAVEATS 
Overflow causes unpredictable results. There are no error 
indications. 
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Fflush,Fclose - flush or close a file 
USAGE 
#include <stdio.h> 


fflush(fp) 
FILE *fp; 


feclose(fp) 
FILE *fp; 


DESCRIPTION 


Fflush causes a buffer associated with the file pointer "fp" 
to be cleared by writing out to the file; of course, only if 
the file was opened for write or update. It is not normally 
necessary to call fflush, but it can be useful when, for 
example, normal output is to "stdout", and it is wished to 
send something to "stderr" which is unbuffered. If fflush 
were not used and "stdout" referred to the terminal, the 
"stderr" message will appear before large chunks of the 
"stdout" message even though the latter was written first. 


Felose calls fflush to clear out the buffer associated with 
"fp", closes the file, and frees the buffer for use by another 
fopen call. 


The exit() system call and normal termination of a program 
causes fclose to be called for each open file. 


SEE ALSO 
System call close(), fopen(), setbuf(). 
DIAGNOSTICS 


EOF is returned if "fp" does not refer to an output file or 
there is an error on writing to the file. 
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Feof,Ferror,Clearerr,Fileno - return status information of files 
USAGE 


#include <stdio.h> 


feof(fp) 
FILE #*fp; 


ferror(fp) 
FILE *fp; 


clearerr(fp) 
FILE #fp; 


fileno(fp) 
FILE *fp; 


DESCRIPTION 


Feof returns non-zero if the file associated with "fp" has 
reached its end. Zero is returned on error. 


Ferror returns non-zero if an error condition occurs on access 
to the file "fp"; zero is returned otherwise. The error 
condition persists, preventing further access to the file by 
other Standard Library functions, until the file is closed, 
or it is cleared by clearerr. 


Clearerr resets the error condition on the file "fp". This 
does NOT "fix" the file or prevent the error from occurring 
again; it merely allows Standard Library functions at least to 
try. 

CAVEATS 


These functions are actually macros that are defined in 
"<stdio.h>" so their names cannot be redeclared. 


SEE ALSO 


System call open(), fopen(). 
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Findstr,Findnstr - string search 
USAGE 


findstr(pos,string, pattern) 
char *string, *pattern; 


findnstr(pos, string, pattern, size) 
char *string, *pattern; 


DESCRIPTION 


These functions search the string pointed to by "string" for 
the first instance of the pattern pointed to by "pattern" 
starting at position "pos" (where the first position is 1 not 
0). The returned value is the position of the first matched 
character of the pattern in the string or zero if a match is 
not found. 


Findstr stops searching the string when a null byte is found in 
"string". 


Findnstr only stops searching at position "pos" + "len" so it 
may continue past null bytes. 


CAVEATS 
The current implementation does not use the most efficient 
algorithm for pattern matching so that use on very long strings 
is likely to be somewhat slower than it might be. 

SEE ALSO 


index() ,rindex. 
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Fopen — open a file and return a file pointer 
USAGE 
#include <stdio.h> 


FILE *fopen( filename, action) 
char *filename, #action; 


FILE *freopen(filename,action, streak) 
char *filename, *action; 
FILE *strean; 


FILE *fdopen(filedes, action) 
int filedes; 
char *action; 


DESCRIPTION 


Fopen returns a pointer to a file structure (file pointer) if 
the file named in the string pointed to by "filename" can be 
validly opened with the action in the string pointed to by 


"action", 


The valid actions are: 


mye open for reading 

wh create for writing 

man append(write) at end of file, or create for 
writing 

Try open for update | 

nw+n create for update 

ta+f create or open for update at end of file 

nqn directory read 


Any action may have an "x" after the initial letter which 
indicates to "fopen()" that it should look in the current 


execution directory if a full path name is not given, 


the x also specifies that the file should have execute 


permission. 
E.g. f = fopen("fred", "wx"); 


Opening for write will perform a "creat()". If a file with the 
same name exists when the file is opened for write, it will be 
truncated to zero length. Append means open for write and 
position to the end of the file. Writes to the file via 
"pute()" ete. will extend the file. Only if the file does not 


already exist will it be created. 
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NOTE that the type of a file structure is pre-defined in 
"stdio.h" as FILE, so that a user program may declare or define 
a file pointer by, for example, FILE #f; 


Three file pointers are available and can be considered open 
the moment the program runs: 
stdin the standard input - equivalent to path number 0 
stdout the standard output - equivalent to path number 1 
stderr standard error output- equivalent to path number 2 


All files are automatically buffered except stderr, unless a 
file is made unbuffered by a call to setbuf() (q.v.). 


Freopen is usually used to attach stdin, stdout, and stderr to 

specified files. Freopen substitutes the file passed to it 
instead of the open stream. The original stream is closed. 
NOTE that the original stream will be closed even if the open 
does not succeed. 


Fdopen associates a stream with a file descriptor. The streams 
type(r,w,a) must be the same as the mode of the open file. 


CAVEATS 
The "action" passed as an argument to fopen must be a pointer 
to a string, NOT a character. For example 
fp = fopen("fred","r"); is correct but 
fp = fopen("fred",'r'); is not. 
DIAGNOSTICS 
Fopen returns NULL (0) if the call was unsuccessful. 


SEE ALSO 


System call open() Fclose() 
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Fread,Fwrite - read/write binary data 
USAGE 
#include <stdio.h> 


fread(ptr, size, number, fp) 
FILE #fp; 


fwrite(ptr, size, number, fp) 
FILE *fp; 


DESCRIPTION 


Fread reads from the file pointed to by "fp". "Number" is the 
number of items of size "size" that are to be read starting at 
"ptr", The best way to pass the argument "size" to fread is by 
using "sizeof", Fread returns’ the number of items actually 
read. 


Fwrite writes to the file pointed to by "fp". "Number" is the 
number of items of size "size" reading them from memory 
starting at "ptr", 

DIAGNOSTICS 
Both functions return O(NULL) at end of file or error. 

SEE ALSO 


System calls read(),write(). Fopen(),getc(),putce(),printf(). 
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Fseek,Rewind,Ftell - position in a file or report current position 
USAGE 

#include <stdio.h> 

fseek(fp, offset, place) 

FILE *fp; 

long offset; 


rewind(fp) 
FILE *fp; 


long ftell(fp) 
FILE *fp; 


DESCRIPTION 
Fseek repositions the next character position of a file for 
either read or write. The new position is at "offset" bytes 
from the beginning of the file if "place" is 0, the current 
position if 1, or the end if 2. Fseek sorts out the special 
problems of buffering. 


NOTE that using "lseek()" on a buffered file will produce 
unpredictable results. 


Rewind is equivalent to "fseek(fp,01,0)". 


Ftell returns the current position, measured in bytes, from the 
beginning of the file pointed to by "fp", 


DIAGNOSTICS 
Fseek returns -1 if the call is invalid. 
SEE ALSO 


System call lseek(). 
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Getc,Getchar - return next character to be read from a file 
USAGE 
#include <stdio.h> 


int getc(fp) 
FILE *fp; 


int getchar() 


int getw(fp) 
FILE #fp; 


DESCRIPTION 


Getc returns the next character from the file pointed to by 
"Ppt, 


Getchar is equivalent to "getc(stdin)". 
Getw returns the next two bytes from the file as an integer. 


Under OS-9 there is a choice of service requests to use when 
reading from a file. "Read()" will get characters up to a 
specified number in "raw® mode i.e. no editing will take 
place on the input stream and the characters will appear to the 
program exactly as in the file. "Readln()", on the other 
hand, will honor the various mappings of characters 
associated with a Serial Character device such as a terminal 
and in any case will return to the caller as soon as a carriage 
return is seen on the input. 


In the vast majority of cases, it is preferable to use 
"readin()" for accessing Serial Character devices and "read()*® 
for any other file input. "Getc()" uses this strategy and, as 
all file input using the Standard Library functions is routed 
through "getc()", so do all the other input functions. The 
choice is made when the first call to "gete()" is made after 
the file has been opened. The system is consulted for the 
status of the file and a flag bit is set in the file structure 
accordingly. The choice may be forced by the programmer by 
setting the relevant bit before a call to "getc()". The flag 
bits are defined in "<stdio.h>" as "_SCF" and "_RBF®" and the 
method is as follows: assuming that the file pointer for the 
file, as returned by "fopen()" is f, 


f->_flag |= _SCF; 
will force the use of "readln()" on input and 


f-> flag |= _RBF; 
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will force the use of "read()". This trick may be played on 
the standard streams "stdin", "stdout" and "stderr" without the 
need for calling "fopen()" but before any input is requested 
from the stream. 

DIAGNOSTICS 
EOF(-1) is returned for end of file or error. 


SEE ALSO 


Pute(),fread(),fopen(),gets() ,ungetc(). 
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Gets, Fgets - input a string 
USAGE 
#include <stdio.h> 


char *gets(s) 
char #s; 


char *fgets(s,n,fp) 
char #s; 
FILE #fp; 

DESCRIPTION 
Fgets reads characters from the file "fp" and places them in 
the buffer pointed to by "s" up to a carriage return('\n') but 
not more than "n" ~ 1 characters. A null character is appended 
to the end of the string. 


Gets is similar to fgets, but gets is applied to "stdin" and no 
maximum is stipulated and the ‘'\n' is replaced by a null. 


Both functions return their first arguments. 
CAVEATS 


The different treatment of the "n" by these functions is 
retained here for portability reasons. 


DIAGNOSTICS 
Both functions return NULL on end-of-file or error. 
SEE ALSO 


Puts() ,getce(),scanf(),fread(). 
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Isalpha, Isupper, Islower, Isdigit,Isalnum, Isspace,Ispunct,Isprint, 
Iscntrl,Isascii - character classification 


USAGE 
#include <ctype.h> 
isalpha(c) 
etc. 

DESCRIPTION 


These functions use table look-up to classify characters 
according to their ascii value. The header file defines them 
as macros which means that they are implemented as fast, in- 
line code rather than subroutines. 


Each results in non-zero for true or zero for false. 


The correct value is guaranteed for all integer values in 
isascii, but the result is unpredictable in the others if the 
argument is outside the range ~-1 to 127. 


The truth tested by each function is as follows: 


isalpha ec is a letter 

isdigit ec is a digit 

isupper ec is an upper case letter 

islower c is a lower case letter 

isalnum ec is a letter or a digit 

isspace ec is a space, tab character, newline, carriage 
return or formfeed 

isecntrl ec is a control character (0 to 32) or DEL (127) 

ispunct ec is neither control nor alpha-numeric 

isprint ec is printable (32 to 126) 

isascii ec is in the range -1 to 127 


Page 4 = 14 


MICROWARE C COMPILER USER'S GUIDE 
C STANDARD LIBRARY 


L3tol,Ltol3 - convert between long integers and 3=-byte integers 
USAGE 
13tol(lp,ecp,n) 
long *lp; 
char cp; 
1tol3(cep,lp,n) 
long *lp; 
char *cp; 
DESCRIPTION 
Certain system values, such as dise addresses, are maintained 
in three-byte form rather than four-byte; these functions 


enable arithmetic to be used on then. 


L3tol converts a vector of "n" three-byte integers pointed to 
by "cp", into a vector of long integers starting at "lp". 


Ltol3 does the opposite. 
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Longjmp,Setjmp - jump to another function 


include <setjmp.h> 


set jmp(env) 
jmp_buf env; 


longjmp(env,val) 
jmp_buf env; 


DESCRIPTION 


These functions allow the return of program control directly to 
a higher level function. They are most useful when dealing 
with errors and interrupts encountered in a low level routine. 


"Goto" in C has scope only in the function in which it is 
used; i.e. the label which is the object of a "goto" may only 
be in the same function. Control can only be transferred 
elsewhere by means of the function call, which, of course, 
returns to the caller. In certain abnormal situations a 
programmer would prefer to be able to start some section of 
code again, but this would mean returning up a ladder of 
function calls with error indications all the way. 


Setjmp is used to "mark" a point in the program where a 
subsequent longjmp can reach. It places in the buffer, defined 
in the header file, enough information for longjmp to restore 
the environment to that existing at the relevant call to 
setjmp. 


Longjmp is called with the environment buffer as an argument 
and also, a value which can be used by the caller of setjmp as, 
perhaps, an error status. 


To set the system up, a function will call setjmp to set up the 
buffer, and if the returned value is zero, the program will 
know that the call was the "first time through". If, however, 
the returned value is non-zero, it must be a longjmp returning 
from some deeper level of the progran. 


NOTE that the function calling setjmp must NOT HAVE RETURNED 


at the time of calling longjmp, and the environment buffer must 
be declared GLOBALLY. 
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Malloc,Free,Calloc - memory allocation 


USAGE 


char *malloc(size) 
unsigned size; 


free(ptr) 
char *ptr; 


char *calloc(nel,elsize) 
unsigned nel,elsize; 


DESCRIPTION 


Malloc returns a pointer to a block of at least "size" free 
bytes. 


Free requires a pointer to a block that has been allocated by 
malloc; it frees the space to be allocated again. 


Calloc allocates space for an array. Nel is the number of 
elements in the array, and elsize is the size of each element. 
Calloc initializes the space to zero. 


DIAGNOSTICS 


Malloc, free, and calloc return NULL(0O) if no free memory can 
be found or if there was an error. 
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Mktemp - create unique temporary file name 


USAGE 


char *mktemp(name) 
char *name; 


DESCRIPTION 
Mktemp may be used to ensure that the name of a temporary file 
is unique in the system and does not clash with any other file 
name. 
"Name" must point to a string whose last five characters are 
nxt; the Xs will be replaced with the ascii representation of 
the task id. 
For example, if "name" points to "foo.XXXXX", and the task id 
is 351, the returned value points at the same place, but it now 
holds "fo00.351". 

SEE ALSO 


System call "getpid()". 
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Printf,Fprintf,Sprintf - formatted output 
USAGE 
#include <stdio.h> 


printf(control [,arg0[,arg1..]]) 
char #control; 


fprintf(fp, control [,arg0[,arg1..]]) 
FILE *fp; 
char *control; 


sprintf(string,control [,arg0[,arg1..]]) 
string []; 
char *control; 


DESCRIPTION 


These three functions are used to place numbers and strings on 
the output in formatted, human readable form. 


Fprintf places its output on the file "fp", printf on the 
standard output, and sprintf in the buffer pointed to by 
"string". NOTE that it is the user's responsibility to ensure 
that this buffer is large enough. 


The "control" string determines the format, type, and number 
of the following arguments expected by the function. If the 
control does not match the arguments correctly, the results 
are unpredictable. 


The control may contain characters to be copied directly to 
the output and/or format specifications. Each format 
specification causes’ the function to take the next successive 
argument for output. 


A format specification consists of a "%" character followed by 
(in this order) : 


An optional minus sign ("=") that means left justification 
in the field. 


An optional string of digits indicating the field width 
required. The field will be at least this wide and may be 
wider if the conversion requires it. The field will be 
padded on the left unless the above minus sign is present, 
in which case it will be padded on the right. The padding 
character is, by default, a space, but if the digit string 
starts with a zero ("0"), it will be "0". 
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An optional dot (".") and a digit string, the precision, 
which for floating point arguments indicates the number 
of digits to follow the decimal point on conversion, and 
for strings, the maximum number of characters from the 
string argument are to be printed. 


An optional character "1" indicates that the following 
md","x", or "o" is the specification of a long integer 


argument. NOTE that _in _order for the printing of long 
integers _to _take i 
somewhere _the _statemen fli ch causes 

e e e . 


A conversion character which shows the type of the 
argument and the desired conversion. The recognized 
conversion characters are: 


d,o,x,X The argument is an integer and the 
conversion is to decimal, octal, or 
hexadecimal, respectively. "X" prints hex 
and alpha in upper case. 


u The argument is an integer and the 
conversion is to an unsigned decimal in 
the range 0 to 65535. 


f The argument is a double, and the form of 
the conversion is "[=-]nnn.nnn",. Where the 
digits after the decimal point are 
specified as above. If not specified, the 
precision defaults to six digits. If the 
precision is 0, no decimal point or 
following digits are printed. 


e,E The argument is a double and the form of 
the conversion is "[-]n.nnne(+or-)nn"; one 
digit before the decimal point, and the 
precision controls the number following. 
"E® prints the "e" in upper case. 


g,G The argument is a double, and either the 
“fn format or the "e" format is chosen, 
whichever is the_ shortest. If the "Gq" 
format is used, the "e" is printed in 
upper case. 


NOTE in each of the above double conversions, the last digit is 
rounded. 


ALSO _NOTE _that in order for the printing of floats or doubles 
to _take _place, _the _source _program _MUST have the statement 
bffinit() somewhere. 
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The argument is a character. 


The argument is ae pointer to a string. 
Characters from the string are printed up 
to a null character, or until the number of 
characters indicated by the precision have 
been printed. If the precision is 0 or 
missing, the characters are not counted. 


No argument corresponding; "%" is printed. 


Kernighan & Ritchie pages 145-147. Pute(),scanf(). 
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Putc,Putchar,Putw - put character or word in a file 
USAGE 
#include <stdio.h> 
char pute(ch,fp) 
char ch; 


FILE *fp; 


char putchar(ch) 
char *ch; 


putw(n, fp) 
FILE *fp; 


DESCRIPTION 


Pute adds the character "ch" to the file "fp" at the current 
writing position and advances the position pointer. 


Putchar is implemented as a macro (defined in the header file) 
and is equivalent to "putc(ch,stdout)". 


Putw adds the (two byte) machine word "n" to the file "fp" in 
the manner of putc. 


Output via pute is normally buffered except 
(a) when the buffering is disabled by "setbuf()", and 
(b) the standard error output is always unbuffered. 
DIAGNOSTICS 


Pute and putchar return the character argument from a 
successful call, and EOF on end-of-file or error. 


SEE ALSO 


Fopen() ,fclose(),fflush(),gete(),puts(),printf(),fread(). 
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Puts,Fputs - put a string on a file 
USAGE 
#include <stdio.h> 


puts(s) 
char &s; 


fputs(s,fp) 

char s; 

FILE *fp; 
DESCRIPTION 


Fputs copies the (null-terminated) string pointed to by "s" 
onto the file "fp", 


Puts copies the string "s" onto the standard output and 
appends "\n", 


The terminating null is not copied by either function. 
CAVEATS 


The inconsistency of the new-line being appended by puts and 
not by fputs is dictated by history and the desire for 
compatibility. 
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Qsort - quick sort 


USAGE 


qsort(base,n,size,compfunc) 

char *base; 

int (*compfunc)(); /* which means: a pointer to a function 
returning an int #/ 


DESCRIPTION 


Qsort implements the quick-sort algorithm for sorting an 
arbitrary array of items. 


"Base" is the address of the array of "n" items of size "size", 
"Compfunc" is a pointer to a comparison routine supplied by 
the user. It will be called by qsort with two pointers to 
items in the array for comparison and should return an integer 
which is less_ than, equal to, or greater than 0 where, 
respectively, the first item is less than, equal to, or greater 
than the second. 
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Seanf,Fscanf,Sscanf - input string interpretation 
USAGE 
#include <stdio.h> 


fscanf(fp,control,[,pointer...]) 
FILE *fp; 
char *control; 


scanf(control[,pointer...]) 
char *control; 


sscanf(string,control[,pointer...]) 
char *string,*control; 


DESCRIPTION 
These functions perform the complement to "printf()" etc. 


Fscanf performs conversions from the file "fp", scanf from the 
standard input, and sscanf from the string pointed to by 
"string". 


Each function expects a control string containing conversion 
specifications, and zero or more pointers to objects into which 
the converted values are stored. 


The control string may contain three types of fields: 

(a) Spaces, tab characters, or "\n" which match any of 
the three in the input. 

(b) Characters not among the above and not "%" which must 
match characters in the input. 

(c) A ngn followed by an optional "#" indicates 
suppression of assignment, an optional field width 
maximum and a conversion character indicating the 
type expected. 


A conversion character controls the conversion to be applied 
to the next field and indicates the type of the corresponding 
pointer argument. A field consists of consecutive non-space 
characters and ends at either a character inappropriate for the 
conversion or when a specified field width is exhausted. 
When one field is finished, white-space characters are passed 
over until the next field is found. 


The following conversion characters are recognized ; 


d A decimal string is to be converted to an integer. 

fe) An octal string; the corresponding argument should 
point to an integer. 

x A hexadecimal string for conversion to an integer. 

s A string of non-space characters is expected and 


will be copied to the buffer pointed to by the 
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corresponding argument anda null ("\0") appended. 
The user must ensure that the buffer is large 
enough. The input string is considered terminated 
by a space, tab or ("\n"). 

c A character is expected and is copied into the byte 
pointed to by the argument. The white-space 
skipping is suppressed for this conversion. Ifa 
field width is given, the argument is assumed to 
point to a character array and the number of 
characters indicated is copied to it. NOTE to ensure 
that the next non-white-space character is read use 
"gis" and that TWO bytes are pointed to by the 
argument. 

e,f A floating point representation is expected on the 
input and the argument must be a pointer to a float. 
Any of the usual ways of writing floating point 
numbers are recognized. 


[ This denotes the start of a set of match characters; 
the inclusion or exclusion of which delimits the 
input field. The white-space skipping is 


suppressed. The corresponding argument should be a 
pointer to a character’ array. If the first 
character in the match string is not """, 
characters are copied from the input as long as they 
can be found in the match string, if the first 
character is the copying continues while characters 
cannot be found in the match string. The match 
string is delimited by a "]", 
D,O,X Similar to d,o,x above, but the corresponding 

argument is considered to point to a long integer. 

E,F Similar to e,f above, but the corresponding argument 
should point to a double. 

% A match for "%" is sought; no conversion takes 
place. 


Each of these functions returns a count of the number of 
fields successfully matched and assigned. 


CAVEATS 


The returned count of matches/assignments does not include 
character matches and assignments suppressed by "#", The 
arguments must ALL be pointers. It is a common error to call 
scanf with the value of an item rather than a pointer to it. 


DIAGNOSTICS 
These functions return EOF on end of input or error and a count 
which is shorter than expected for unexpected or unmatched 
items. 


SEE ALSO 
Atoi(),Atof(),Gete(),Printf() Kernighan and Ritchie pp 147-150 
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Setbuf - fix file buffer 
USAGE 
#include <stdio.h> 
setbuf(fp, buffer) 


FILE *fp; 
char *buffer; 


DESCRIPTION 


When the first character is written to or read from a file 
after it has been opened by "fopen()", a buffer is obtained 
from the system if required and assigned to it. Setbuf may be 
used to forestall this by assigning a user buffer to the file. 


Setbuf must be used after the file has been opened and before 
any I/O has taken place. 


The buffer must be of sufficient size and a value for a 
manifest constant, BUFSIZ, is defined in the header file for 
use in declarations. 


If the "buffer" argument is NULL (0), the file becomes un- 
buffered and characters are read or written singly. 


NOTE that the standard error output is unbuffered and the 
standard output is buffered. 


SEE ALSO 


fopen() ,getc(),pute(). 
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Sleep - stop execution for a time 
USAGE 


sleep(seconds) 
unsigned seconds; 


DESCRIPTION 


The current task is stopped for the specified time. 
If "seconds" is zero, the task will sleep for one tick. 
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Streat, Strneat, Stremp, Strnomp, Strepy, Strhepy, Strnepy, 
Strlen,Index, Rindex- string functions 


USAGE 


char *streat(s1,s2) 
char #s1,#s2; 


char *strncat(s1,s2,n) 
char *s1,#s2; 
int n; 


stremp(s1,s2) 
char #s1,#s2; 


char ®strhcpy(s1,s2) 
char *s1,*s2; 


strnemp(s1,s2,n) 
char *s1,#s2; 
int n; 


char *strepy(s1,s2) 
char *s1,#s2; 


char *strnepy(s1,8s2,n) 
char *s1,#s2; 
int n; 


strlen(s) 
char #s; 


char #index(s, ch) 
char #s,ch; 


char *rindex(s,ch) 
char #*s,ch; 


DESCRIPTION 


All strings passed to these functions are assumed null- 
terminated. 


Streat appends a copy of the string pointed to by "s2" to the 
end of the string pointed to by "si". Strncat copies at most 
"n" characters. Both return the first argument. 


Stremp compares’ strings "si" and "s2" for lexicographic order 
and returns an integer less than, equal to or greater than 0 
where, respectively, "si" is less than, equal to or greater 
than "s2", Strnemp compares at most "n" characters. 
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Strepy copies characters from "s2" to the space pointed to by 
"si" up to and including the null byte. Strnepy copies exactly 
*" characters. If the string "s2" is too short, the "si" will 
be padded with null bytes to make up the difference. If "s2" 
is too long, "si" may not be null-terminated. Both functions 
return the first argument. 


Strhepy copies string with sign bit terminator. 
Strlen returns the number of non-null characters in "s", 


Index returns a pointer to the first occurrence of "ch" in "gs" 
or NULL if not found. 


Rindex returns a pointer to the last occurrence of "ch" in "s® 
or NULL if not found. 


CAVEATS 
Streat and strecpy have no means of checking that the space 
provided is large enough. It is the user's responsibility to 
ensure that string space does not overflow. 


SEE ALSO 


Findstr(). 
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System ~- shell command request 


USAGE 


system(string) 
char *®string; 


DESCRIPTION 


System passes its argument to "shell" which executes it as a 
command line. The task is suspended until the shell command 


is completed and system returns the shell's exit status. 


maximun length of string is 80 characters. If a longer string 


is needed, use os9fork. 
SEE ALSO 


System calls "os9fork()", "wait()". 
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Toupper,Tolower - character translation 


#include <ctype.h> 


int toupper(c) 
int ¢@; 


etc. 


int _toupper(c) 
int ec; 


int _tolower(c) 
int ¢c; 


DESCRIPTION 


The functions toupper and tolower have as their domain the 
integers in the range -1 through 255. Toupper converts lower- 
case to upper-case, and tolower converts upper-case to lower- 
case. All other arguments are returned unchanged. 


The macros _toupper and _tolower do the same things as the 
corresponding functions, but they have restricted domains and 
they are faster. The argument to _toupper must be lower-case, 
and the argument to -—_tolower must be upper-case. Arguments 
that are outside each macros domain, such as passing a lower- 
case to _tolower, yield garbage results. 
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Ungete - put character back on input 
USAGE 
#include <stdio.h> 
ungete(ch,fp) 
char ch; 
FILE *fp; 
DESCRIPTION 


This function alters the state of the input file buffer such 
that the next call of "gete()" returns "ch", 


Only one character may be pushed back, and at least one 
character must have been read from the file before a call to 
ungetc. 

"Fseek()" erases any pushback. 


DIAGNOSTICS 


Ungete returns its character argument unleSs no pushback could 
occur, in which case EOF is returned. 


SEE ALSO 


getc(),fseek() 
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COMPILER GENERATED ERROR MESSAGES 


Below is a list of the error messages that the C compiler generates, 
and, if applicable, probable causes and the K & R Appendix A section 
number (in parenthesis) to see for more specific information. 


already a local variable 
Variable has already been declared at the current block level. 
(8.1, 9.2) 


argument ;: <text> 
Error from preprocessor. Self-explanatory. Most common cause 
of this error is not being able to find an include file. 


argument error 
Function argument declared as type struct, union, or function. 
Pointers to such types, however, are allowed. (10.1) 


argument storage 
Function arguments may only be declared as_ storage class 
register. (10.1) 


bad character 
A character not in the C character set (probably a control 
char) was encountered in the source file. (2) 


both must be integral 
>> and << operands cannot be FLOAT or DOUBLE. (7.5) 


break error 
The break statement is allowed only inside a while, do, for, or 
switch block. (9.8) 


can't take address 
& operator is not allowed on a register variable. Operand must 
otherwise be an lvalue. (7.2) 


cannot cast 
Type result of cast cannot be FUNCTION or ARRAY. (7.2, 8.7) 


cannot evaluate size 
Could not determine size from declaration or initializer. 
(8.6, 14.3) 


cannot initialize 
Storage class or type does not allow variable to be 
initialized. (8.6) 


compiler trouble 
Compiler detected something it couldn't handle. Try compiling 
the program again. If this error still occurs, contact Radio 
Shack. 
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condition needed 
While, do, for, switch, and if statements require a condition 
expression. (9.3) 


constant expression required 
_Initializer expressions for static or external variables cannot. 
reference variables. They may, however, refer to the address 
of a previously declared variable. This installation allows no 
initializer expressions unless all operands are of type INT or 
CHAR (8.6) 


constant overflow 
Input numeric constant was too large for the implied or 
explicit type. (2.6, [PDP-11]) 


constant required 
Variables are not allowed for array dimensions or cases. (8.3, 
8.7, 9.7) 


continue error 
The continue statement is allowed only inside a while, do, or 
for block. (9.9) 


declaration mismatch 
This declaration conflicts with a previous one. This is 
typically caused by declaring a function to return a non- 
integer type after a reference has been made to the function. 
Depending on the line structure of the declaration block, this 
error may be reported on the line following the erroneous 
declaration. (11, 11.1 11.2) 


divide by zero 
Divide by zero occurred when evaluating a constant expression. 


? expected | 
? dis any character that was expected to appear here. Missing 
semicolons or braces cause this error. 


expression missing 
An expression is required here. 


function header missing 
Statement or expression encountered outside a function. 
Typically caused by mismatched braces. (10.1) 


function type error 
A function cannot be declared as returning an array, function, 
struct, or union. (8.4, 10.1) 


function unfinished 
End-of-file encountered before the end of function definition. 
(10.1) 


identifier missing 
Identifier name required here but none was found. 
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illegal declaration 
Declarations are allowed only at the beginning of a block. 
(9.2) 


label required 
Label name required on goto statement. (9.11) 


label undefined 
Goto to label not defined in the current function. (9.12) 


lvalue required 
Left side of assignment must be able to be "stored into", 
Array names, functions, structs, etc. are not lvalues. (7.1) 


multiple defaults 
Only one default statement is allowed in a switch block. (9.7) 


multiple definition 
Identifier name was declared more than once in the same block 
level (9.2, 11.1) 


must be integral 
Type of object required here must be type int, char, or 
pointer. 


name clash 
Struct-union member and tag names must be mutually distinct. 
(8.5) 


name in a cast 
Identifier name found in a cast. Only types are allowed. (7.2, 


8.7) 


named twice 
Names in a function parameter list may appear only once. (10.1) 


no 'if' for ‘else! 
Else statement found with no matching if. This is typically 
caused by extra or missing braces and/or semicolons. (9.3) 


no switch statement 
Case statements can only appear within a switch block. (9.7) 


not a function 
Primary in expression is not type "function returning...". If 
this is really a function call, the function name was declared 
differently elsewhere. (7.1) 


not an argument 
Name does not appear in the function parameter list. (10.1) 


operand expected 


Unary operators require one operand, binary operators two. 
This is typically caused by misplaced parenthesis, casts or 
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operators. (7.1) 
out of memory 

Compiler dynamic memory overflow. The compiler requires 
dynamic memory for symbol table entries, block level 
declarations and code generation. Three major factors affect 
this memory usage. Permanent declarations (those appearing on 
the outer block level (used in include files)) must be reserved 
from the dynamic memory for the duration of the compilation of 
the file. Each { causes the compiler to perform a block-level 
recursion which may involve "pushing down" previous 
declarations which consume memory. Auto class initializers 
require saving expression trees until past the declarations 
which may be very memory-expensive if they exist. Avoiding 
excessive declarations, both permanent and inside compound 
statement blocks, conserve memory. If this error occurs on an 
auto initializer, try initializing the value in the code body. 


pointer mismatch 
Pointers refer to different types. Use a cast if required. 
(7.1) 


pointer or integer required 
A pointer (of any type) or integer is required to the left of 
the '=->' operator. (7.1) 


pointer required 
Pointer operand required with unary * operator. (7.1) 


primary expected 
Primary expression required here. (7.1) 


should be NULL 
Second and third expression of ?: conditional operator cannot 
be pointers to different types. If both are pointers, they 
must be of the same type or one of the two must be null. (7.13) 


##88 STACK OVERFLOW #88# 
Compiler stack has overflowed. Most likely cause is very deep 
lock-level nesting or hundreds of switch cases. 


storage error 
Reg and auto storage classes may only be used within functions. 
(8.1) 


struct member mismatch 
Identical member names in two different structures must have 
the same type and offset in both. (8.5) 


struct member required 
Identifier used with . and => operators must be a structure 
member name. (7.1) 


struct syntax 
Brace, comma, etc. is missing in a struct declaration. (8.5) 
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struct or union inappropriate 
struct or union cannot be used in this context. 


Syntax error 
Expression, declaration, or statement is incorrectly formed. 


third expression missing 
? must be followed by a : with expression. This error may be 
caused by unmatched parenthesis or other errors in the 
expression. (7.13) 


too long 
Too many characters provided in a string initializing a 
character array. (8.6) 


too many brackets 
Unmatched or unexpected brackets encountered processing an 
initializer. (8.6) 


too many elements 
More data items supplied for aggregate level in initializer 
than members of the aggregate. (8.6) 


type error 
Compiler type matching error. Should never happen. 


type mismatch 
Types and/or operators in expression do not correspond. (6) 


typedef - not a variable 
Typedef type name cannot be used in this manner. (8.8) 


undeclared variable 
No declaration exists at any block level for this identifier. 


undefined structure 
Union or struct declaration refers to an undefined structure 
name. (8.5) 


unions not allowed 
Cannot initialize union members. (8.6) 


unterminated character constant 
Unmatched ' character delimiters. (2.4.3) 


unterminated string 
Unmatched " string delimiters. (2.5) 


while expected 
No while found for do statement. (9.5) 
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COMPILER PHASE COMMAND LINES 


This appendix describes the command lines and options for the 
individual compiler phases. Each phase of the compiler may be 
executed separately. The following information describes’ the 
options available to each phase. 


ecl & ec2 (C executives): 
ce [options] file {file} [options] 


Recognized file suffixes: 


.c C source file 
a Assembly language source file 
r Relocatable module format file 


Recognized options: (UPPER and lower case is equiv.) 
-a Suppress assembly. Leave output in ".a" file. 
-e=n Edition number (n) is supplied to ec.prep for 


inclusion in module psect and/or to c.link for 
inclusion as the edition number of the linked 


module. 
-0 Inhibits assembler code optimizer pass. 
=p Invoke compiler function profiler. 
-r Suppress link step. Leave output in ".r" file. 


-m=<size> Size in pages (in kbytes if followed by a K) of 


additional memory the linker should allocate to 


object module. 
-l=<path> Library file for linker to search before the 
standard library. 


-f=<path> Overrride other output naming. Module name (in 
object module) is the last name in the pathlist. 


-f is not allowed with -a or -r. 
=-C Output comments in assembly language code. 
-S Suppress generation of stack-checking code. 
-~d<NAME> Is equiv to #define <NAME> 1 in the 


preprocessor. -d<NAME>=<STRING> is equivalent to 


#define <NAME> <STRING>. 


-n=<name> output module name. <name> is used to override 
the -f default output name. 


CC1 only: 

-x Create, but do not execute c.com command file. 
CC2 only: 

-q Quiet mode. Suppress echo of file names. 
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e.prep (C macro preprocessor) 
e.prep [options] <path> 


<path> is read as input. C.prep causes c.comp to generate a 
psect directive with the last element of the pathlist and _c as 
the psect name. If <path> is /d0/myprog.c, the psect name is 
myprog._c. Output is always to stdout. 


Recognized options: 
@-l Cause c.comp to copy source lines to assembly 
output as comments. 
-E=<n> 
-e=<n> Use <n> as psect edition number. 
-D<NAME> Same as described above for ecct1/cc2. 


e.comp (One-pass compiler) 
e.comp [options] [<file>] [options] 


If <file> is not present, c.comp will read stdin. Input text 
need not be c.prep output, but no preprocessor directives are 
recognized (#include, #define, macros etc.). Output assembly 
code is normally to stdout. Error message output is always 
written to stdout. 


Recognized options; 
-s Suppress generation of stack checking code. 
-p Generate profile code. 
-o=<path> Write assembly output to <path>. 


ec.pass1 (Pass One of Two-pass Compiler) 
c.pass2 (Pass Two of Two-pass Compiler) 


c.pass1 [options] [<file>] [options] 
e.pass2 [options] [<file>] [options] 


Command line and options are the same as c.comp. If the 
options given to c.pass1 are not given to c.pass2 also, c.pass2 
will not be able to read the c.passi output. Both c.pass1 and 
c.pass2 read stdin and write stdout normally. 
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c.opt (Assembly code optimizer) 

ec.opt [<inpath>] [<outpath>] 

C.opt reads stdin and writes stdout. <inpath> must be present 

if <outpath> is given. Since c.opt rearranges and changes 

code, comments and assembler directives may be rearranged. 
c.asm (Assembler) 


c.asm <file> [options] 


C.asm reads <file> as assemble language input. Errors are 
written to stderr. Options are turned on or off by the 
inclusion of the option character preceeded by a '-', 


Recognized options: 
-o=<path> Write relocatable output to path. Must be a 


disk file. 
-1 Write listing to stdout. (default off) 
=-c List conditional assembly lines. (default on) 
~f Formfeed for top of form. (default off) 
-g List all code bytes generated. (default off) 
-X Suppress macro expansion listing. (default on) 
=e Print errors. (default on) 
-s Print symbol table. (default off). 
-dn Set lines per page to n. (default 66). 
-wn Set line width to n. (default 80). 


e.link (Linker) 
e.link [options] <mainline> [<sub1> {<subn>} ] [options] 


C.link turns c.asm output into executable form. All input 
files must contain relocatable object format (ROF) files. 
<mainline> specifies the base module from which to resolve 
external references. A mainline module is indicated by setting 
the type/lang value in the psect directive non-zero. No other 
ROF can contain a mainline psect. The mainline and all 
subroutine files will appear in the final linked object module 
whether actually referenced or not. 


For the C Compiler, cstart.r is the mainline module. It is the 
mainline module's job to perform the initialization of data and 
the relocation of any data-text and data-data references within 
the initialized data using the information in the object module 
supplied by c.link. 
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(c.link continued) 


Recognized options: 


-~o=<path> 


-n=<name> 
-l=<path> 


-E=<n> 
~e=<n> 


~M=<size> 


-b=<ept> 


=-t 


Linker object output file must be a disk 

file. The last element in <path> is used as the 
module name unless overridden by -n. 

Use <name> as output module name. 

Use <path> as library file. A library file 
consists of one or more merged assembly ROF 
files. Each psect in the file is checked to see 
if it resolves any unresolved references. If 
so, the module is included in the final output 
module, otherwise it is skipped. No mainline 
psects are allowed in a library file. Library 
files are searched in the order given on the 
command line. 


<n> is used for the edition number in the final 
output module. 1 is used if -e is not present. 
<size> indicates the number of pages (kbytes if 
size is followed by a K) of additional memory, 
e.link will allocate to the data area of the 
final object module. If no additional memory is 
given, c.link adds up the total data stack 
requirements found in the psect of the modules 
in the input modules. 

Prints linkage map indicating base addresses of 
the psects in the final object module. 

Prints final addresses assigned to symbols in 
the final object module. 

Link C functions to be callable by BASICO9. 
<ept> is the name of the function to be 
transferred to when BASICO9 executes the RUN 
command. 

Allows static data to appear in a BASICO9 calle 
able module. It is assumed the C function call- 
ed and the calling BASICO9 program have provided 
a sufficiently large static storage data area 
pointed to by the Y register. 
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USING AND LINKING TO USER DEFINED LIBRARIES 


A library consists of a group of "C" procedures or functions that 
have been separately compiled into Relocatable Object Files (ROF) 
and subsequently merged into one library file. 


If, hypothetically, you had created a set of higher level mathematic 
functions, that you wanted to convert into a "C" library. First you 
would separately compile each one using the -R option. Then you 
would merge them all into one large library file. If you need to 
scan the library file for available functions you can use the 
example program "RDUMP.C" to inspect any "C" library file. 


For example: 
0S9:CC1 SIN.C COS.C TAN.C ARCOS.C -R 
0S9:CC1 ARCSIN.C ARCTAN.C EXP.C LOG.C -R 
0S9:CC1 NLOG.C SQRT.C SQR.C CUBE.C -R 


Then you would: 

OS9:MERGE SIN.R COS.R TAM.R ARCOS.R >TEMP1 
OS9:MERGE ARCSIN.R ARCTAN.R EXP.R LOG.R >TEMP2 
OS9:MERGE NLOG.R SQRT.R SQR.R CUBE.R >TEMP3 
OS9:MERGE TEMP1 TEMP2 TEMP3 >TRIG.L 


Then to use the library simply use the -l=<pathlist> option in your 
command line when you compile your progran. 


When the linker is executed the pathlist specified will be searched 
to resolve any references made to the functions within the library. 
The linker searches all specified libraries in the order specified 
before searching the standard library. The linker will resolve all 
references on a first found basis. This means that the linker will 
use the first procedure or function whose name matches a reference 
to that name and will ignore any additional functions found that 
have the same name. 


Procedures or functions within a library that use other functions 
within the same library should always appear first. For example, in 
the above example if the "ARCSIN"®" routine used the "SIN" routine, 
the "SIN" routine should be merged into the library file after the 
"ARCSIN". Another way of putting this is that all references to 
other procedures within a library should be forward references. 
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INTERFACING TO BASICO9 


The object code generated by the Microware C Compiler can be made 
callable from the BASICO9 "RUN" statement. Certain portions of a 
BASICO9 program written in C can have a dramatic effect on execution 
speed. To effectively utilize this feature, one must be familiar 
with both C and BASICO9 internal data representation and procedure 
calling protocol. 


C type "int" and BASICO9 type "INTEGER" are identical; both are two 
byte two's complement integers. C type "char" and BASICOQ9 type 
"BYTE" and "BOOLEAN" are also identical. Keep in mind that C will 
sign-extend characters for comparisons yielding the range -128 to 
127. 


BASICO9 strings are terminated by Oxff (255). C strings are 
terminated by 0x00 (0). If the BASICO9 string is of maximum length, 
the terminator is not present. Therefore, string length as well as 
terminator checks must be performed on BASICO9 strings when 
processing them with C functions. 


The floating point format used by C and BASICOY are not directly 
compatible. Since both use a binary floating point format it is 
possible to convert BASICO9 reals to C doubles and vice-versa. 


Multi-dimensional arrays are stored by BASICO9 in a different manner 
than C. Multi-dimensional arrays are stored by BASICO9 in a column- 
wise manner; C stores them row-wise. Consider the following 
example: 


BASICO9 matrix: DIM array(5,3): INTEGER. 

The elements in consecutive memory locations (read left to 
right, line by line) are stored as: 

(1,1) ,(2,1),(03,1),(4,1),(5,1) 

(1,2),(2,2),(03,2),(4,2),(5,2) 

(1,3) ,(2,3),(3,3),(4,3),(5,3) 


C matrix: int array[5][({3]; 

The elements in consecutive memory locations (read left to 
right, line by line) are stored as: 

(1,1),(1,2),(1,3) 

(2,1),(2,2),(2,3) 

(3,1),(3,2),(3,3) 

(4,1) ,04,2),(4, 3) 

(5,1),(5,2),(5,3) 


Therefore to access BASICO9 matrix elements in C, the subscripts 
must be transposed. To access element array(4,2) in BASICO9 use 
array[2][4] inc. 


The details on interfacing BASICO9 to C are best described by 
example. The remainder of this appendix is a mini tutorial 


demonstrating the process starting with simple examples and working 
up to more complex ones. 
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EXAMPLE 1 - SIMPLE INTEGER ARITHMETIC CASE 


This first example illustrates a simple case. Write a C function to 
add an integer value to three integer variables. 


build bt1.c 
? addints(cnt,value,s1,arg1,82,arg2,83,arg3,34) 
? int *value, *arg1, *arg2, *arg3; 


? { 

? #farg1 += #value; 
? farg2 += #value; 
? #arg3 += value; 
? 3 

? 


That's the C function. The name of the function is "addints", The 
name is information for C and c.link; BASICO9 will not know anything 
about the name. Page 9-13 of the BASICO9 Reference manual describes 
how BASICO9 passes parameters to machine language modules. Since 
BASICO9 and C pass parameters in a similar fashion, it is easy to 
access BASICO9 values. The first parameter on the BASICO9 stack is 
a two byte count of the number of following parameter pairs. Each 
pair consists of an address and size of value. For most C 
functions, the parameter count and pair size is not used. fhe 
address, however, is the useful piece of information. The address 
is declared in the C function to always be a "pointer to..." type. 
BASICO9 always passes addresses’ to procedures, even for constant 
values. The arguments cnt, s1, s2, 83, and s4 are just place 
holders to indicate the presence of the parameter count and argument 
sizes on the stack. These can be used to check validity of the 
passed arguments if desired. 


The line "int #value, *arg1,*arg2,*arg3" declares the parameters (in 
this case all "pointers to int"), so the compiler will generate the 
correct code to access the BASICO9 values. The remaining lines 
increment each arg by the passed value. Notice that a simple 
arithmetic operation is performed here (addition), so C will not 
have to call a library function to do the operation. 


To compile this function, the following C compiler command line is 
used: 


ec2 bti.ec -rs 


Cc2 uses the Level-Two compiler. Replace cc2 with cc1 if you are 
using the Level-One compiler. The -r option causes the compiler to 
leave bt1.r as output, ready to be linked. The -s option suppresses 
the call to the stack checking function. Since we will be making a 
module for BASICO9, cstart.r will not be used. Therefore, no 
initialized data, static data, or stack checking is allowed. More 
on this later. 
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The bti.r file must now be converted to a loadable module that 
BASICO9 can link to by using a special linking technique as follows: 


c.link bti.r -bsaddints -ozsaddints 


This command tells the linker to read bti.r as input. The option 
"-b=addints" tells the linker to make the output file a module that 
BASICO9 can link to and that the function "addints" is to be the 
entrypoint in the module. You may give many input files to c.link 
in this mode. It resolves references in the normal fashion. The 
name given to the "=-b=" option indicates which of the functions is 
to be entered directly by the BASICO9 RUN command. The option 
"-o=addints" says what the name of the output file is to be, in this 
case "addints", This name should be the name used in the BASICO9 
RUN command to call the C procedure. The name given in the "-o=" 
option is the name of the procedure to RUN. The "=b=" option is 
merely information to the linker so it can fill in the correct 
module entrypoint offset. 


Enter the following BASICO9 program: 


PROCEDURE btest 

DIM i,j,k: INTEGER 
i=1 

j=132 

k=-1033 

RUN addints(4,i, j,k) 
PRINT i,j,k 

END 


When this procedure is RUN, it should print: 
5 136 -1029 


indicating that our C function worked! 
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EXAMPLE 2 - MORE COMPLEX INTEGER ARITHMETIC CASE 


The next example shows how static memory area can be used. Take the 
C function from the previous example and modify it to add the number 
of times it has been entered to the increment: 


build bt2.c 
static int entcnt; 


addints(cnt, cmem, cmemsiz,value,si1,arg1,82,arg2,83,arg3,s4) 
char *cmen; 
int #value, *arg1, *arg2, targ3; 
{ 
#asm 
ldy 6,s base of static area 
#endasm 
int j = #value + entcnt++; 


farg1 += 
®arg2 += 
farg3 += 


OVNI VON W VON VW VW VW WW YD 
Cire Cre Ce 
we we WO 


This example differs from the first in a number of ways. The line 
"static int entcent" defines an integer value named entcnt global to 
bt2.c. The parameter ecmem and the line "char ®cmem" indicate a 
character array. The array will be used in the C function for 
global/static storage. C accesses non-auto and non-register 
variables indexed off the Y register. Cstart.r normally takes care 
of setting this up. Since cstart.r will not be used for this 
BASICO9 callable function, we have to take measures to make sure the 
Y register points to a valid and sufficiently large area of memory. 
The line "ldy 6,s" is assembly language code embedded in C source 
that loads the Y register with the first parameter passed by 
BASICO9. If the first parameter in the BASICO9 RUN statement is an 
array, and the "ldy 6,s" is placed IMMEDIATELY after the "{" opening 
the function body, the offset will always be "6,s". Note the line 
beginning "int j = ...". This line uses an initializer which, in 
this case, is allowed because j is of class "auto". No classes but 
"auto" and "register" can be initialized in BASICO9 callable C 
functions. 


To compile this function, the following C compiler command line is 
used; 


ec bt2.ec -rs 
Where ce is ccl or cc2. 


Again, the -r option leaves bt2.r as output and the -s option 
suppresses stack checking. 


Normally, the linker considers it to be an error if the "=b=" option 
appears and the final linked module requires a data memory 
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allocation. In our case here, we require a data memory allocation 
and we will provide the code to make sure everything is set up 
correctly. The "jt" linker option causes the linker to print the 
total data memory requirement so we can allow for it rather than 
complaining about it. Our linker command line is: 


c.link bt2.r -ozaddints -b=addints -t 


The linker will respond with "BASICO9 static data size is 2 bytes". 
We must make sure cmem points to at least 2 bytes of memory. The 
memory should be zeroed to conform to C specifications. 


Enter the following BASICO9 program: 


PROCEDURE btest 

DIM i, j,k,n: INTEGER 
DIM cmem(10): INTEGER 
FOR i=1 TO 10 


emem(i)=0 
NEXT i 
FOR n=1 TO 5 
is1 
j=132 
k=-1033 


RUN addints(cmem,4,i, j,k) 
PRINT i,j,k 

NEXT n 

END 


This program is similar to the previous example. Our area for data 
memory is a 10 integer array (20 bytes) which is way more than the 2 
bytes for this example. It is better to err on the generous side. 
Cmem is an integer array for convenience in initializing it to zero 
(per C data memory specifications). When the program is run, it 
calls addints 5 times with the same data values. Because addints 
adds the number of times it was called to the value, the i,j,k 
values should be 4+number of times called. When run, the program 
prints: 


5 136 -1029 
6 137 -1028 
T 138 -1027 
8 139 - 1026 
9 140 -1025 


Works again! 
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EXAMPLE 3 - SIMPLE STRING MANIPULATION 


example shows how to access’ BASICO9 strings through C 


functions. For this example, write the C version of SUBSTR: 


build bt3.c 


? 
? 
? 
? 
? 
? 
? 
? 
? 
? 
? 
? 
? 
? 
? 
? 
? 
? 
? 
? 
? 
? 
? 
? 
? 
? 
? 
? 
? 
? 
? 
? 
? 


/* Find substring from BASICO9 string: 
RUN findstr(A$,B$,fndpos) 

returns in fndpos the position in A$ that B$ was found or 
0 if not found. A$ and B$ must be strings, fndpos must be 
INTEGER. . 

#/ 

findstr(cnt,string,strent,srchstr,srchcnt,result) 

char *string,*srchstr; 

int strent,srchent, *result; 


{ 
} 
static finder(str,strlen, pat, patlen) 


char *str,*pat; 
int strlen, patlen; 


*result = finder(string,strent,srchstr,srchcnt) ; 


{ 
int i; 
for(iz=1;strlen-- > 0 && *strJ=Oxff; ++1) 
if(smatch(str++,pat,patlen) ) 
return i; 
} 


static smatch(str,pat,patlen) 
register char str, *pat; 
int patlen; 


{ 
while(patlen-- > 0 && *pat != Oxff) 
if(#str++ != *#*pat++) 
return 0; 
return 1; 
} 


Compile the program: 


ce bt3.c -rs 
Where ce is cel or cac2 


And link it: 


C. 


link bt3.r -osfindstr -b=findstr 
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The BASICO9 test program is: 


PROCEDURE btest 

DIM a,b: STRING[20] 

DIM matchpos: INTEGER 

LOOP 

INPUT "String ",a 

INPUT "Match ",b 

RUN findstr(a,b,matchpos) 

PRINT "Matched at position ",matchpos 
ENDLOOP 


When the program is run, it should print the position where the 
matched string was found in the source string. 


Page C-7 


MICROWARE C COMPILER USER'S GUIDE 
APPENDIX C 


EXAMPLE 4 - QUICKSORT 
The next example programs demonstrate how one might implement a 
quicksort written in C to sort some BASICO9 data. 
C integer quicksort program: 
#define swap(a,b) { int t; tza; a=b; b=t; } 
/* qsort to be called by BASICO9: 


dim d(100):INTEGER any size INTEGER array 
run cqsort(d,100) calling qsort. 


#/ 

qsort(argent,iarray,iasize,icount,icsiz) 

int argent, /* BASICOQ argument count #/ 
iarray[], /* Pointer to BASICO9 integer array */ 
iasize, /* and it's size #/ 
#icount, /* Pointer to BASICO9 (sort count) #/ 
icsiz; /* Size of integer #/ 

{ 


sort(iarray,0,#icount); /* initial qsort partition #/ 
} 


/* standard quicksort algorithm from Horowitz-Sahni #/ 
static sort(a,m,n) 

register int *a,m,n; 

{ 


register i,j,x; 


if(m <n) { 
i m; 
j n+ 13 
x = a[{m]j; 
for(;;) { 
do i+= 1; while(afi] < x); /#* left partition #/ 
do j -= 1; while(a[j] > x); /*# right partition #/ 
if(i < j) 
swap(a[ij,a{j]) /* swap */ 
else break; 


} 

swap(a{m],a(j]); 

sort(a,m, j-1); /* sort left #/ 
sort(a, j+1,n);3 /* sort right #/ 
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The BASICO9 program is: 


PROCEDURE sorter 
DIM i,n,d(1000): INTEGER 
n=1000 

i=RND(-(PI)) 

FOR i=1 TO n 
d(i):=sINT(RND( 1000) ) 
NEXT i 

PRINT "Before:;" 

RUN prin(1,n,d) 

RUN qsortb(d,n) 
PRINT "After:" 

RUN prin(1,n,qd) 

END 


PROCEDURE prin 

PARAM n,m,d(1000): INTEGER 
DIM i: INTEGER 

FOR i=n TO m 

PRINT d(i); * "; 

NEXT i 

PRINT 

END 


C string quicksort program: 


/* qsort to be called by BASICO9: 

dim cmemory:STRING[10] This should be at least as large as 
the linker says the data size should 
be. 

dim d(100): INTEGER Any size INTEGER array. 


run cqsort(cmemory,d,100) calling qsort. Note that the pro- 
cedure name run is the linked O0S-9 
subroutine module. The module name 
need not be the name of the C func- 


tion. 

#/ 
int maxstr; /* string maximum length */ 
static strbemp(stri1,str2) /* basicO9 string compare #/ 
register char *stri,*str2; 
{ 

int maxlen; 

for (maxlen = maxstr; *str1 == *str2 3;++str1) 

if (maxlen-- > 0 {| *str2++ == Oxff) 


return 0; 
return (*#str1 - #str2); 


Page C-9 


MICROWARE C COMPILER USER'S GUIDE 
APPENDIX C 


essort(argent,stor,storsiz,iarray,iasize,elemlen,elsiz, 
icount,icsiz) 


int argent; /* BASICO9 argument count #/ 
char *stor; /* Pointer to string (C data storage) */ 
char iarray[]; /* Pointer to BASICO9 integer array */ 
int iasize, /* and it's size #/ 
#elemlen, /* Pointer integer value (string length) #/ 
elsiz; /* Size of integer */ 
#icount, /* Pointer to integer (sort count) #/ 
icsiz; /* Size of integer #/ 


{ 

/* The following assembly code loads Y with the first 
arg provided by BASICO9. This code MUST be the first code 
in the function after the declarations. This code assumes the 
address of the data area is the first parameter in the BASICO9 
RUN command. #/ 


#fasm 
ldy 6,s get addr for C data storage 
#endasm 


/* Use the C library qsort function to do the sort. Our 
own BASICOQ string compare function will compare the strings. 


#/ 
qsort(iarray, #*icount,maxstr=*elemlen,strbemp); 
} 
/* define stuff ecstart.r normally defines */ 
#asm 
_stkcheck: 


rts dummy stack check function 


vsect 
errno: rmb 2 C function system error number 
_flace;: rmb 8 C library float/long accumulator 
endsect 
#endasm 


The BASICO9 calling program: (words file contains strings to sort) 


PROCEDURE ssorter 

DIM a(200):STRING[20] 
DIM cmemory: STRING[20] 
DIM i,n: INTEGER 

DIM path: INTEGER 

OPEN #path, "words"; READ 


n=100 

FOR i=1 TO n 

INPUT #path,a(i) 

NEXT i 

CLOSE #path 

RUN prin(a,n) 

RUN cssort(cmemory,a,20,n) 
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RUN prin(a,n) 
END 


PROCEDURE prin 

PARAM a(100):STRING([20]; n: INTEGER 
DIM i: INTEGER 

FOR i=1 TO n 

PRINT i; ™® "3 a(i) 

NEXT i 

PRINT 

END 


The next example shows how to access BASICO9 reals from C functions: 


flmult(cnt, cmemory,cmemsiz,realarg,realsize) 


int ent; /* number of arguments */ 
char *cmemory; /* pointer to some memory for C use #/ 
double #realarg; /* pointer a real */ 
{ 
#asm 
ldy 6,s get static memory address 
#endasm 


double number; 


getbreal(&number,realarg); /* get the BASICO9 real */ 
number #= 2.; /* number times twot/ 
putbreal(realarg, énumber) ; /* give back to BASICO9 #/ 


} 


/* getbreal(creal, breal) 
get a 5=-byte real from BASICO9 format to C format #/ 


getbreal(creal,breal) 
double #creal, *breal; 


{ 
register char ®cr,*br; /* setup some char pointers #/ 
cr = creal; 
br = breal; 

#asn 

* At this point U reg contains address of C double 

# 0,8 contains address of BASICO9 real 


ldx 0,s get address of B real 


clra clear the C double 
clrb 

std 0,u 

std 2,u 

std 4,u 

stb 6,u 

ldd 0,x 
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beq g3 BASICO9 real is zero 


ldd 1,x get hi B mantissa 
anda #$7f. clear place for sign 
std 0,u put hi C mantissa 
ldd 3,x get lo B mantissa 
andb #$fe mask off sign 
std 2,u put lo C mantissa 
lda 4,x get B sign byte 
lsra shift out sign 
bec gi 
lda 0,u get C sign byte 
ora #$80 turn on sign 
sta 0,u put C sign byte 
g1 1lda 0,x get B exponent 
suba #128 excess 128 
sta 7,u put C exponent 
g3 clra clear carry 
#endasm 


} 


/* putbreal(breal,creal) 
put C format double into a 5=byte real from BASICO9 #/ 


putbreal(breal,creal) 
double *breal,*creal; 


{ 
register char *cr,*br; /* setup some char pointers #/ 
cr = creal; 
br = breal; 

#fasm 

# At this point U reg contains address of C double 

# 0,8 contains address of BASICO9 real 


ldx 0,s get address of B real 


lda 7,u get C exponent 
bne pO not zero? 

clra clear the BASICO9 
clrb real 

std 0,x 

std 2,x 

sta 4,x 

bra p3 and exit 


pO ldd 0,u get hi C mantissa 

ora #$80 this bit always on for normalized real 
std 1,x put hi B mantissa 

ldd 2,u get lo C mantissa 

std 3,x put lo B mantissa 

incb round mantissa 

bne pt 

ine 3,x 

bne pl 
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ine 2,x 

bne pl 

ine 1,x 
pi andb #$fe turn off sign 
stb 4,x put B sign byte 
lda 0,u get C sign byte 
lsla shift out sign 

bee p2 bra if positive 
orb #$01 turn on sign 
stb 4,x put B sign byte 
p2 lda 7,u get C exponent 
adda #128 less 128 

sta 0,x put B exponent 
p3 clra clear carry 
#endasm 


} 


/* replace ecstart.r definitions for BASICO9 #/ 
#asm 
_stkcheck: 
_stkchee: 
rts 


vsect 
_flace: rmb 8 
errno: rmb 2 

endsect 
#endasm 


BASICO9 calling program: 


PROCEDURE btest 

DIM a: REAL 

DIM i: INTEGER 

DIM cmemory:STRING[ 32] 

a=i. 

FOR i=1 TO 10 
RUN flmult(cmemory,a) 
PRINT a 

NEXT i 

END 
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The last program is an example of accessing BASICOQ matrix elements. 
The C program: 


matmult(cent,cmemory,cmemsiz,matxaddr,matxsize, scalar,scalsize) 


char *cmemory; /* pointer to some memory for C use #/ 
int matxaddr[5][3]; /* pointer a double dim integer array */ 
int *scalar; /* pointer to integer *#/ 
{ 
#asm 
ldy 6,s get static memory address 
#endasm 
int i,j; 


for(i=0; 1i<53 ++i) 
for(j=1; j<33 ++) 
matxaddr[jJ[i] *= *scalar; /#® multiply by value 

#/ 

} 
#asm 
_stkcheck: 
_stkchec: 

rts 


vsect 
_flace: rmb 8 
errno: rmb 2 

endsect 
#endasm 


BASICO9 calling progran: 


PROCEDURE btest 
DIM im(5,3): INTEGER 
DIM i,j: INTEGER 
DIM cmem:STRING[ 32] 
FOR i=1 TO 5 

FOR j=1 TO 3 

READ im(i, j) 

NEXT j 
NEXT i | 
DATA 11,13,7,3,4,0,5,7,2,8,15,0,0,14,4 
FOR i=1 TO 5 

PRINT im(i,1),im(i,2),4m(i, 3) 
NEXT i 
PRINT 
RUN matmult(cmem,im,64) 
FOR isi TO 5 

PRINT im(i,1),im(i,2),im(i, 3) 
NEXT i 
END 


Page C-14 


MICROWARE C COMPILER USER'S GUIDE 
APPENDIX D 


RELOCATING MACRO ASSEMBLER REFERENCE 


This appendix gives a summary of the operation of the "Relocating 
Macro Assembler" (named c.asm as distributed with the C Compiler). 
This appendix and the example assembly source files supplied with 
the C compiler’ should provide basic information on how to use the 
"Relocating Macro Assembler" to create relocatable-object format 
files (ROF). It is further assumed that you are familiar with the 
6809 instruction set and mnemonics. See the Microware Relocating 
Assembler Manual for a more detailed description. The main function 
of this appendix is to enable the reader to understand the output 
produced by c.asm. The Relocating Macro Assembler allows programs 
to be compiled separately and then linked together, and it also 
allows macros to be defined within programs. 


Differences between the Relocating Macro Assembler(RMA) and the 
Microware Interactive Assembler(MIA): 


RMA is does not have an interactive mode. Only a disk file is 
allowed as input. 


RMA output is an ROF file. The ROF file must be processed by 
the linker to produce an executable OS9 memory module. The 
layout of the ROF file is described later. 


RMA has a number of new directives to control the placement of 
eode and data in the executable module. Since RMA does not 
produce memory modules, the MIA directives "mod" and "emod" are 
not present. Instead, new directives PSECT and VSECT control 
the allocation of code and data areas by the linker. 


RMA has no equivalent to the MIA "setdp" directive. Data (and 
DP) allocation is handled by the linker. 
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Symbolic Names, 


A symbolic name is valid if it consists of from one to nine 
uppercase or lowercase characters, decimal digits or the characters 
ngn om tm) of. or «6me@M, = =6RMA does not fold lowercase letters to 
uppercase. The names "Hi.you" and "HI.YOU" are distinct names. 


Label field. 


If a symbolic name in the label field of a source statement is 
followed by a "™:" (colon), the name will be known GLOBALLY (by all 
modules linked together). If no colon appears, the name will be 
known only in the PSECT in which it was defined. PSECT will be 
described later. 


Undefined names. 


If a symbolic name is used in an expression and hasn't been defined, 
RMA assumes the name is external to the PSECT. RMA will record 
information about the reference so the linker can adjust the operand 
accordingly. External names cannot appear in operand expressions 
for assembler directives. 


Listing format. 


00098 0032 59 + rolb 
00117 O0O045=17ffb8 label lbsr _dmove Comment 


| | | { { Start of comment 
l | { | ! Start of operand 

1 | } | Start of mnemonic 

1] ! Start of label 

i} A "+" indicates a line generated by a macro 
i | expansion. 

{Start of object code bytes. 

An "=" here indicates that the operand contains an 

{ external reference. 

| Location counter value. 

Line number. 


Section location counters. 
Each section contains the following location counters; 


PSECT - instruction location counter 

VSECT - initialized direct page location counter 
non-initialized direct page location counter 
initialized data location counter 
non-initialized data location counter 

CSECT - base offset counter 


Section directives. 


RMA contains 3 section directives. PSECT indicates to the linker 
the beginning of a relocatable-object-format file(ROF) and 
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initializes the instruction and data location counters and assembles 
code into the ROF object code area. VSECT causes RMA to change to 
the data location counters and place any generated code into the 
appropriate ROF data area. CSECT initializes a base value for 
assigning offsets to symbols. The end of these sections is 
indicated by the ENDSECT directive. 


The source statements placed in a particular section cause the 
linker to perform a function appropriate for the statement. 
Therefore, the mnemonics allowed within a section are restricted as 
follows: 


These mnemonics are allowed inside or outside any section: nan, 
opt, ttl, pag, spe, use, fail, rept, endr, ifeq, ifne, iflt, 
ifle, ifge, ifgt, ifp1, ende, else, equ, set, macro, endn, 
esect, and endsect. 


Within a CSECT: rmb. 


Within a PSECT: any 6809 instruction mnemonic, fcc, fdb, feces, 
feb, rzb, vsect, endsect, os9 and end. 


Within a VSECT: rmb, fcc, fdb, fes, feb, rzb and endsect. 
PSECT directive. 


The main difference between PSECT and MOD is that MOD set up 
information for OS-9 and PSECT sets up information for. the 
linker(c.link in the C compiler). 


PSECT {name,typelang,attrrev,edition, stacksize,entrypoint} 


name Up to 20 bytes (any printable character except space 
or comma) for a name to be used by the linker to 
identify this PSECT. This name need not be distinct 
from all other PSECTs linked together, but it helps 
to identify PSECTs the linker has a problem with if 
the names are different. 


typelang byte expression for the executable module type/lang- 
uage byte. If this PSECT is not a "mainline"(a 
module that has been designed to be forked to) mod- 
ule this byte must be zero. 


attrrev byte expression for executable module attribute/rev- 
ision byte. 


edition byte expression for executable module edition byte. 


stacksize word expression estimating the amount of stack stor- 
age required by this psect. The linker totals this 
value in all PSECTs to appear in the executable mod- 
ule and adds this value to any data storage require- 
ment for the entire progran. 
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entrypoint word expression entrypoint offset for this PSECT. 
If the PSECT is not a mainline module, this should 
be set to zero. 


PSECT must have either no operand list or an operand list containing 
a name and five expressions. If no operand list is provided, the 
PSECT name defaults to "program" and all other expressions to zero. 
There can only be one PSECT per assembly language file. 


The PSECT directive initializes all counter orgs and marks the start 
of the program module. No VSECT data reservations or object code 
may appear before or after the PSECT/ENDSECT block. 


Example: 
psect myprog, Prgrm+0Objct, Reent+1,Edit,0,progent 
psect another_prog,0,0,0,0,0 


VSECT directive. 
VSECT {DP} 


The VSECT directive causes RMA to change to the data location 
counters. If DP appears after VSECT, the direct page counters are 
used, otherwise the non-direct page data is used. The RMB directive 
within this section reserves the specified number of bytes in the 
appropriate uninitialized data section. The fec, fdb, feces, feb and 
rzb (reserve zeroed bytes) directives place data into the 
appropriate initialized data section. If an operand for fdb or feb 
contains an external reference, this information is placed in the 
external reference part of the ROF to be adjusted at link or 
execution time. ENDSECT marks the end of the VSECT block. Any 
number of VSECT blocks can appear within a PSECT. Note, however, 
that the data location counters maintain their values between one 
VSECT block and the next. Since the linker handles the actual data 
allocation, there is no facility provided to adjust the data 
location counters. 


CSECT directive. 

CSECT {expression} 
The CSECT directive provides a means for assigning consecutive 
offsets to labels without resorting to EQUs. If the expression is 
present, the CSECT base counter is set to that value, otherwise it 
is set to zero. 
RZB statement. 
syntax: RZB <expression> 


The reserve zeroed bytes pseudo-instruction generates sequences of 
zero bytes in the code or initialized data sections, the number of 
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which is specified by the expression. 


COMPARISON BETWEEN ASSEMBLY PROGRAMS FOR THE MICROWARE INTERACTIVE 
ASSEMBLER AND THE RELOCATING MACRO ASSEMBLER 


The following two program examples simply fork BASICO9. 
examples are to show some of the differences in the 
The differences are apparent. 


of the 


relocating assembler. 


# this program forks basic09 


PRGRM 
OBJCT 


stk 
name 
prm 


prmsize 


entry 


ifpt 
use ..../defs/os9defs.a 
endc 


equ $10 
equ $01 


equ 200 
psect rmatest, $11,$81,0,stk,entry 


fes /basic09/ 
feb $D 
equ *-prm 


leax name,pcer 
leau prm,per 

ldy #prmsize 

lda #PRGRM+0OBJCT 
clrb 

os9 F$FORK 

os9 FS$WAIT 


os9 F$EXIT 


endsect 


MACRO INTERACTIVE ASSEMBLER SOURCE 


prnam 
type 
revs 


name 
prm 
prmsize 


ifp1 
use defsfile 
endc 


mod siz,prnanm,type,revs,start,size 
fes /testshell/ 

set prgrm+objct 

set reent+1 


rmb 250 

rmb 200 

fes /basic0d9/ 
$D 


equ *-prm (continued) 
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size equ . 

start equ # 
leax name,pcer 
leau prm,per 
ldy #prmsize 
lda #PRGRM+OBJCT 
clrb 
os9 F$FORK 
os9 F$WAIT 
os9 F$EXIT 
emod 

siz equ 
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MACROS 


Sometimes identical or similar sequences of instructions may be 
repeated in different places in a program. The problem is that if 
the sequence of instructions is long or must be used a number of 
times, writing it repeatedly can be tedious. 


A macro is a definition of an instruction sequence that can be 
used numerous places within a program. The macro is given a name 
which is used similarly to any other instruction mnemonic. Whenever 
RMA encounters the name of a macro in the instruction field, it 
outputs all the instructions given in the macro definition. In 
effect, macros allow the programmer to create "new" machine language 
instructions. 


For example, suppose a program frequently must perform 16 bit 
left shifts of the D register. The two instruction sequence can be 
defined as a macro, for example: 


dasl macro 
aslb 
rola 
endm 


The "macro" and "endm" directives specify the beginning and the 
end of the macro definition, respectively. The label of the "macro" 
directive specifies the name of the macro, "dasl" in this example. 
Now the "new" instruction can be used in the progran: 


ldd 12,s get operand 
dasl double it 
std 12,8 Save operand 


In the example above, when RMA encountered the "dasl" macro, it 
actually outputted code for "aslb" and "rola". Normally, only the 
macro name is listed as above, but an RMA option can be used to 
cause all instructions of the "macro expansion" to be listed. 


Macros should not be confused with subroutines although they 
are Similar in some ways. Macros repetitively duplicate an "in 
line*" code sequence every time they are used and allow some 
alteration of the instruction operands. Subroutines appear exactly 
once, never change, and are called using special instructions (BSR, 
JSR, and RTS). In those cases where they can be used 
interchangeably, macros usually produce longer but slightly faster 
programs, and subroutines produce shorter and slightly slower 
programs. Short macros (up to 6 bytes or so) will almost always be 
faster and shorter than subroutines because of the overhead of the 
BSR and RTS instructions needed. 
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MACRO STRUCTURE 


A macro definition consists of three sections: 


1. The macro header - assigns a name to the macro 
2. The body - contains the macro statements 
3. The terminator - indicates the end of the macro 


<name> MACRO /* macro header #/ 
body /* macro body */ 
ENDM /* macro terminator #/ 


The macro name must be defined by the label given in the MACRO 
statement. The name can be any legal assembler label. It is 
possible to redefine the 6809 instructions (LDA, CLR, etc.) 
themselves by defining macros having identical names. Caution: 
redefinition of assembler directives such as "RMB" can have 
unpredictable consequences. 


The body of the macro can contain any number of legal RMA 
instruction or directive statements including references’ to 
previously defined macros. The last statement of a macro definition 
must be ENDM. 


The text of macro definitions are stored on a temporary file 
that is created and maintained by RMA. This file has a large (1K 
byte) buffer to minimize disk accesses. Therefore, programs that 
use more than 1K of macro storage space should be arranged so that 
short, frequently used macros are defined first so they are kept in 
the memory buffer instead of disk space. 


Macro calls may be nested, that is, the body of a macro 
definition may contain a call to another macro. For example: 


times} MACRO 
dasl 
dasl 
ENDM 


The macro above consists of the "dasl" macro used twice. The 
definition of a new macro within another is not permitted. Macro 
calls may be nested up to eight deep. 
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MACRO ARGUMENTS 


Arguments permit variations in the expansion of a macro. 
Arguments can be used to specify operands, register names, 
constants, variables, etc., in each occurence of a macro. 


A macro can have up to nine formal arguments in the operand 
fields. Each argument consists of a backslash character and the 
sequence number of the formal argument, e.g, \1, \2 ... \9. When 
the macro is expanded, each formal argument is replaced by the 
corresponding text string "actual argument" given in the macro call. 
Arguments can be used in any part of the operand field not in the 
instruction or label fields. Formal arguments can be used in any 
order and any number of times. 


For example, the macro below performs the typical instruction 
sequence to create an OS-9 file: 


create MACRO 


leax \1,per get addr of file name string 
lda #\2 set path number 

ldb #\3 set file access modes 

os9 I$CREATE 

ENDM 


This macro uses three arguments: "\1" for the file name string 
address; "\2" for the path number; and "\3" for the file access mode 
code. When "create" is referenced, each argument is replaced by the 
corresponding string given in the macro call, for example: 


create outname,2,$1E 
The macro call above will be expanded to the code sequence: 


leax outname,per 
lda #22 

ldb #$1E 

os9 I$CREATE 


If an argument string includes special characters such as 
backslashes or commas, the string must be enclosed in double quotes. 
For example, this macro reference has two arguments: 


double count,"2,s" 
An argument may be declared null by omitting all or some 


arguments in the macro call to make the corresponding argument an 
empty string so no substitution occurs when it is referenced. 
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There are two special argument operators that can be useful in 
constructing more complex macros. They are: 


\Ln - Returns the length of the actual 
argument n, in bytes. 


\# - Returns the number of actual arguments 
passed in a given macro call. 


These special operators are most commonly used in conjunction with 
RMA's conditional assembly facilities to test the validity of 
arguments used in a macro call, or to change the way a macro works 
according to the actual arguments used. When macros are performing 
error checking they can report errors using the FAIL directive. 
Here is an example using the "create" macro given on the previous 
page but expanded for error checking: 


create MACRO 


ifne \# - 3 must have exactly 3 args 
FAIL create: must have three arguments 
endc 


ifgt \L1 - 29 file name can be 1 = 29 chars 
FAIL create: file name too long 


ende 

leax \1,per get addr of file name string 
lda #\2 set path number 

ldb #\3 set file access modes 

os9 I$CREATE 

ENDM 
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MACRO AUTOMATIC INTERNAL LABELS 


Sometimes it is necessary to use labels within a macro. Labels 
are specified by "\@", Each time the macro is called, a unique 
label will be generated to avoid multiple definition errors. Within 
the expanded code "\@" will take on the form "@xxx", where xxx will 
be a decimal number between 000 to 999. . 


More than one label may be specified in a macro by the addition 
of an extra character(s). For example, if two different labels are 
required in a macro, they can be specified by "\@A" and "\@B". In 
the first expansion of the macro, the labels would be "@001A" and 
"@001B", and in the second expansion they would be "@002A" and 
"O02B"., The extra characters may be appended before the "\" or 
after the "@", 


Here is an example of macro that uses internal labels: 


testovr MACRO 


empd #\1 compare to arg 
bls \@A bra if in range 
orce #1 set carry bit 
bra \@B and skip next instr. 
\@A andec #$FE clear carry 
\@B equ # continue... 


Suppose the first macro call is: 
testovr $80 
The expansion will be: 


empd #$80 compare to arg 


bls @O01A bra if in range 
oree #1 set carry bit 
bra @001B and skip next instr. 
@001A andce #$FE clear carry 
@001B equ # continue... 


If the second macro call is; 
testovr 240 
The expansion will be: 


empd #240 compare to arg 


bls @002A bra if in range 
orece #1 set carry bit 
bra @002B and skip next instr. 
@002A andeec #$FE clear carry 
@002B equ a continue... 
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ADDITIONAL COMMENTS ABOUT MACROS 


Macros can be an important and useful programming tool that can 
Significantly extend RMA's capabilities. In addition to creating 
instruction sequences, they can also be used to create complex 
constant tables and data structures. 


Macros can also be dangerous in the sense that if they are used 
indiscriminately and unnecessarily they can impair the readability 
of a program and make it difficult for programmers other than the 
original author to understand the program logic. Therefore, when 
macros are used they should be carefully documented. 
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INDEX 
abort 3-2 getchar 4-11 qsort yo2h 
abs 3-3 getime 3-35 read 3-32 
access 3-4 getpid 3-15 readln 3-32 
atof Hu 3 gets yo13 rewind 4-10 
atoi 4m 3 getstat 3-16 rindex 4-30 
atol yu3 getuid 3-18 sbrk 3-33 
ecalloc 4-17 getw Ko 11 scanf ye25 
chain 3-5 ibrk 3-33 setbuff 4-27 
ehdir 3-6 index 430 setime 3-35 
chmod 3-7 intercept 3-19 set jmp 4-16 
chown 3-8 isalnum yeh setpr 3-34 
ehxdir 3-6 isalpha yo14 setstat 3-37 
clearerr youd isascii yoy setuid 3-36 
close 3-9 isentrl yo14 signal 3-38 
ere 3-10 isdigit yo14 sleep 4-28 
creat 3-11 islower eS sprintf 4m19 
defdrive 3-12 isprint ho14 sscanf Ye2d 
dup 3-13 ispunct Ho14 stacksize 3-39 
exit 3-14 isspace yoy streat 429 
fclose yoy isupper Ho14 stremp 4-29 
fdopen Lo kill 3-21 strepy 4-30 
feof Hod 13tol He15 strhepy 4-30 
ferror yod long jmp H-16 strlen 4-30 
fflush yoy lseek 3-22 strncat 4-29 
fgets Yo13 1ltol3 ye 15 strnepy K-30 
fileno 4o5 malloc 4-17 system = 31 
findnstr 1 mknod 3-23 toascii Yo 32 
findstr 4—6 mktemp 418 tolower 4-32 
fopen Yo7 modlink 3-24 toupper Yo 32 
fprintf yn19 modload 3-24 tsleep 3-42 
fputs Yu 23 munlink 3-25 ungetec 4-32 
fread eye open 3-28 unlink 3-43 
free Ho17 os9fork 3-29 wait 3-44 
freemem 3-40 pause 3-30 write 3-45 
freopen heT prerr 3-31 writeln 3-45 
fscanf Ye25 printf 4e19 _exit 3-13 
fseek 4-10 pute 4-22 _0s9 3-25 
ftell 4-10 putchar 422 _strass 4-41 
fwrite 4-9 puts 4-23 _tolower 4-32 
gete 4m41 putw Ye22 _toupper 4-32 
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ADDITIONAL COMMENTS ABOUT MACROS 


Macros can be an important and useful programming tool that can 
Significantly extend RMA's capabilities. In addition to creating 
instruction sequences, they can also be used to create complex 
constant tables and data structures. 


Macros can also be dangerous in the sense that if they are used 
indiscriminately and unnecessarily they can impair the readability 
of a program and make it difficult for programmers other than the 
original author to understand the program logic. Therefore, when 
macros are used they should be carefully documented. 
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INDEX 
abort 3-2 getchar 4-11 qsort 42h 
abs 3-3 getime 3-35 read 3-32 
access 3-4 getpid 3-15 readin 3-32 
atof 4-3 gets 4-13 rewind 4-10 
atoi Yo3 getstat 3-16 rindex 4-30 
atol yu3 getuid 3-18 sbrk 3-33 
calloc 4o17 getw 4m11 scanf ye25 
chain 3-5 ibrk 3-33 setbuff Ym2T 
chdir 3-6 index 430 setime 3=35 
chmod 3-7 intercept 3-19 setjmp yo16 
chown 3-8 isalnum yo 14 setpr 3-34 
ehxdir 3-6 isalpha yo14 setstat 3-37 
clearerr youd isascii yum 14 setuid 3-36 
close 3-9 isentrl yo14 signal 3-38 
ere 3-10 isdigit yoy sleep 4-28 
creat 3-11 islower yoy sprintf 4-19 
defdrive 3-12 isprint yoy sscanf ym 25 
dup 3-13 ispunct yuo ty stacksize 3-39 
exit 3-14 isspace 4-14 streat Ym29 
fclose yoy isupper yo1y stremp 4-29 
fdopen HoT kill 3-21 strepy 4-30 
feof ~ Yad 13tol ye15 strhepy 4-30 
ferror yeod long jmp 4-16 strlen 4—30 
fflush yoy lseek 3-22 strneat Yu29 
fgets Yo13 1ltol3 ye15 strnepy Ye 30 
fileno youd malloc K-17 system 4-31 
findnstr ey) mknod 3-23 toascii Yo 32 
findstr 4—6 mktemp 4o18 tolower 4-32 
fopen yoT modlink 3-24 toupper 4-32 
fprintf 419 modload 3-24 tsleep 3-42 
fputs Yo 23 munlink 3-25 ungetc Yo 32 
fread 4-9 open 3-28 unlink 3-43 
free Ho17 os9fork 3-29 wait 3-44 
freemem 3-40 pause 3-30 write 3-45 
freopen YoT7 prerr 3-31 writeln 3-45 
fscanf yo2d printf yo19 exit 3-13 
fseek 4=10 pute Ye22 _osg 3-25 
ftell 4-10 putchar 4-22 _strass yo 
fwrite eye) puts 4-23 _tolower 4-32 
gete 4m11 putw He22 _toupper 4-32 
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